@hydranium/core 1.0.0-next.10

package/src/langium/build-phase-pass/build-phase-pass-service.ts

@@ -0,0 +1,141 @@
+/********************************************************************************
+ * 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 { Logger, type Tracer } from '@hydranium/protocol';
+import { DocumentState, type LangiumDocument } from '@hydranium/langium';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServices } from '../module.js';
+import { Registry } from '../../util/registry.js';
+import { type BuildPhasePass, type BuildPhasePassRegistry } from './build-phase-pass.js';
+
+/**
+ * Public contract for the shared build-phase-pass runner. Extends the
+ * {@link BuildPhasePassRegistry} (the imperative `register` surface
+ * contributions and framework self-registration use) with the dispatch entry
+ * point called cross-class from
+ * `BuildPipelineIntegration`
+ * as the batch reaches each wired phase.
+ *
+ * Shared-tier (not per-language): a pass operates on the whole built batch, and
+ * per-language work (integrity) fans out by language *inside* its pass. This
+ * also keeps one priority space per phase across framework and adopter passes,
+ * which is the point — `runPasses` orders the framework's integrity and
+ * profiler-flush passes against adopter passes deterministically.
+ */
+export interface BuildPhasePassService extends BuildPhasePassRegistry {
+   /**
+    * Run every pass declaring `phase` as its state, in priority order,
+    * sequentially — each pass is awaited before the next begins. The cancel
+    * token is checked before each pass so a preempted build stops cleanly.
+    * No-ops when no pass targets the phase. Called by
+    * `BuildPipelineIntegration` from an `onBuildPhase` listener.
+    */
+   runPasses(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void>;
+}
+
+/** Construction options for {@link DefaultBuildPhasePassService}. */
+export type BuildPhasePassServiceOptions = LogNameOptions;
+
+/**
+ * Default {@link BuildPhasePassService}. Generic registry for batch-level
+ * build-phase work, the `onBuildPhase` sibling of
+ * `DefaultAstExtensionService`
+ * (which is per-node, `onDocumentPhase`). This class owns the registry +
+ * priority-ordered dispatch; the listener lifecycle lives in
+ * `BuildPipelineIntegration`,
+ * which calls {@link runPasses} from its `onBuildPhase` listeners.
+ *
+ * **Performance:** {@link runPasses} shares the bucket-by-state cache pattern
+ * with the AST-extension service — the per-state pass list is rebuilt lazily
+ * only after a register / unregister, so steady-state dispatch allocates
+ * nothing and early-outs when no pass targets the phase.
+ *
+ * **Profiling:** mirrors the AST-extension / integrity idiom — a debug-gated
+ * `ProfileSession` scopes each pass by its
+ * `id`, so `report('debug')` emits one self-time line per pass. At the default
+ * `info` level no session is allocated.
+ */
+export class DefaultBuildPhasePassService implements BuildPhasePassService {
+   protected readonly passes = new Registry<BuildPhasePass>();
+   /** Per-state bucket of passes targeting each state, rebuilt lazily on the first run after a registry mutation. */
+   protected stateBuckets = new Map<DocumentState, readonly BuildPhasePass[]>();
+   protected stateBucketsFor: readonly BuildPhasePass[] | undefined;
+
+   protected readonly tracer: Tracer;
+
+   constructor(services: ServerSharedServices, options: BuildPhasePassServiceOptions = {}) {
+      this.tracer = services.Tracer.for(options.logName ?? 'BuildPhasePass').trace('instantiated');
+
+      // Read the shared `buildPhasePasses` contribution group and let each
+      // contribution register one or many passes through this service. The `??`
+      // fallback tolerates incomplete test stubs; production wiring provides the
+      // slot via `createServerSharedModule` + adopter modules.
+      const contributions = services.buildPhasePasses ?? {};
+      for (const contribution of Object.values(contributions)) {
+         contribution.registerBuildPhasePasses(this);
+      }
+   }
+
+   register(pass: BuildPhasePass): Disposable {
+      return this.passes.register(pass);
+   }
+
+   async runPasses(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void> {
+      const bucket = this.getStateBucket(phase);
+      if (bucket.length === 0) {
+         return;
+      }
+      // Per-pass self-time profiling is opt-in: only open a session when the
+      // debug threshold is active, so the production path allocates nothing and
+      // the dispatch loop stays a single const-branch off `session`.
+      const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`build-phase-pass ${DocumentState[phase]}`) : undefined;
+      for (const pass of bucket) {
+         if (cancelToken.isCancellationRequested) {
+            break;
+         }
+         // Scope per pass id so the session aggregates self-time by pass across
+         // the phase; off the profiling path call directly. `scope` awaits an
+         // async `run`, so timing covers the full settle.
+         if (session) {
+            await session.scope(pass.id, () => pass.run(documents, cancelToken));
+         } else {
+            await pass.run(documents, cancelToken);
+         }
+      }
+      // One line per pass (count + self-% + self-ms), sorted — only when profiling.
+      session?.report('debug');
+   }
+
+   /**
+    * Bucket-by-state view of {@link passes}, rebuilt lazily when the registry's
+    * cached `all()` reference changes. Each bucket preserves the registry's
+    * priority order (`Registry.all()` is already priority-sorted).
+    */
+   protected getStateBucket(phase: DocumentState): readonly BuildPhasePass[] {
+      const current = this.passes.all();
+      if (this.stateBucketsFor !== current) {
+         const next = new Map<DocumentState, BuildPhasePass[]>();
+         for (const pass of current) {
+            let bucket = next.get(pass.state);
+            if (!bucket) {
+               bucket = [];
+               next.set(pass.state, bucket);
+            }
+            bucket.push(pass);
+         }
+         this.stateBuckets = next;
+         this.stateBucketsFor = current;
+      }
+      return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+   }
+}
+
+/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
+const EMPTY_STATE_BUCKET: readonly BuildPhasePass[] = Object.freeze([]);

package/src/langium/build-phase-pass/build-phase-pass.ts

@@ -0,0 +1,123 @@
+/********************************************************************************
+ * 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 DocumentState, type LangiumCoreServices, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type RegistryItem } from '../../util/registry.js';
+
+/**
+ * A unit of whole-batch work run once per build when the batch reaches a
+ * declared build phase, ordered by {@link RegistryItem.priority}.
+ *
+ * **Granularity.** This is the batch-level (`documents[]`) sibling of the
+ * node-level registries `AstExtension` (per node, `onDocumentPhase`) and
+ * `IntegrityRule` (per node, dispatched from a framework-registered pass of this
+ * kind). A `BuildPhasePass` rides Langium's native `onBuildPhase` signature
+ * directly — it is handed the whole built batch and owns its own walk, for work
+ * that needs cross-document ordering, rather than having the framework drive a
+ * per-node `streamAllContents` walk.
+ *
+ * **Ordering.** {@link RegistryItem.priority} orders passes WITHIN one phase,
+ * never across phases, because each phase has its own bucket. Lower runs first;
+ * ties break by registration order. Passes in a bucket run sequentially — each
+ * is awaited before the next begins. This is the framework's single declared
+ * insertion point for build-phase work: an adopter pass that must run after a
+ * framework pass declares a higher priority instead of relying on DI
+ * construction order.
+ *
+ * **Priority bands.** `priority` defaults to `0` ({@link RegistryItem.priority}).
+ * The framework reserves NEGATIVE priorities for *foundational* passes that must
+ * precede adopter work regardless of registration order — notably integrity
+ * (`INTEGRITY_PASS_PRIORITY`), which cleans/mutates the AST every derived-state
+ * pass reads. Adopter passes therefore use `0` or higher, which puts them after
+ * the foundational band without declaring anything; chained adopter passes order
+ * among themselves with increasing values. Adopters do NOT need a negative
+ * priority — that band is the framework's.
+ *
+ * **Async + cancellation.** {@link run} may be sync or async; an async pass is
+ * awaited so the next pass sees its full effect. The dispatcher checks the
+ * cancel token before each pass, so a build preempted mid-phase stops cleanly
+ * rather than running the remaining passes against a doomed build.
+ */
+export interface BuildPhasePass extends RegistryItem {
+   /**
+    * The single build phase whose `onBuildPhase` fires this pass. The framework
+    * wires a listener for the same phase set as AST extension; a pass declaring
+    * any other state type-checks but never fires.
+    */
+   state: DocumentState;
+   /**
+    * Run this pass against the whole built batch. May mutate and reparse
+    * documents — the framework's integrity pass does — or derive cross-document
+    * state. Honour `cancelToken` for long walks; the dispatcher already checks
+    * it between passes.
+    */
+   run(documents: readonly LangiumDocument[], cancelToken: CancellationToken): void | Promise<void>;
+}
+
+/**
+ * Group a build batch by the language that owns each document, preserving the
+ * batch's order within each group.
+ *
+ * **Why a pass needs this.** A {@link BuildPhasePass} is handed the whole batch
+ * with no language dimension — unlike its node-level siblings `AstExtension`
+ * and `IntegrityRule`, which the framework resolves per document before calling
+ * them. In a single-grammar workspace that difference is invisible. In a
+ * multi-grammar one, a pass that reaches for `services.language.<anything>`
+ * silently applies the FIRST language's services to every document in the
+ * batch, including documents of the other grammar; nothing errors, and the
+ * result is derived state computed against the wrong grammar's rules.
+ *
+ * Documents whose URI matches no registered language are omitted — a pass
+ * cannot meaningfully run a language's services over them, and throwing would
+ * fail the whole build over one stray URI.
+ */
+export function groupDocumentsByLanguage<TLanguage extends LangiumCoreServices>(
+   services: { ServiceRegistry: { hasServices(uri: URI): boolean; getServices(uri: URI): TLanguage } },
+   documents: readonly LangiumDocument[]
+): Map<TLanguage, LangiumDocument[]> {
+   const grouped = new Map<TLanguage, LangiumDocument[]>();
+   for (const document of documents) {
+      if (!services.ServiceRegistry.hasServices(document.uri)) {
+         continue;
+      }
+      const language = services.ServiceRegistry.getServices(document.uri);
+      const group = grouped.get(language);
+      if (group) {
+         group.push(document);
+      } else {
+         grouped.set(language, [document]);
+      }
+   }
+   return grouped;
+}
+
+/**
+ * Registry handed to a {@link BuildPhasePassContribution}. Implemented by the
+ * `BuildPhasePassService`; doubles
+ * as the low-level imperative API the framework uses to self-register its own
+ * passes (integrity, the Langium profiler flush).
+ */
+export interface BuildPhasePassRegistry {
+   register(pass: BuildPhasePass): Disposable;
+}
+
+/**
+ * Declarative registration of build-phase passes. Bound under the shared
+ * module's `buildPhasePasses` contribution group; the
+ * `BuildPhasePassService` reads its
+ * own group at construction and calls this method, handing itself in as the
+ * registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface BuildPhasePassContribution {
+   registerBuildPhasePasses(registry: BuildPhasePassRegistry): void;
+}

package/src/langium/build-phase-pass/index.ts

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * 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 * from './build-phase-pass.js';
+export * from './build-phase-pass-service.js';

package/src/langium/config/index.ts

@@ -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 * from './settings.js';

package/src/langium/config/settings.ts

@@ -0,0 +1,353 @@
+/********************************************************************************
+ * 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 ObservableValue } from '@hydranium/protocol';
+import { Emitter } from 'vscode-languageserver';
+import { type ServerSharedServices } from '../module.js';
+
+/** True only when `T` is exactly `unknown` (distinguishing it from `any`). */
+type IsUnknown<T> = unknown extends T ? ([T] extends [never] ? false : T extends never ? false : true) : false;
+
+/**
+ * Union of valid path tuples through `T` — manually unrolled to four levels
+ * (TS conditional-type recursion saturates around depth 5 and trips
+ * "instantiation excessively deep" through generic helpers). LSP config trees
+ * are almost always <= 3 levels in practice.
+ */
+type Path<T> = T extends object
+   ? {
+        [K in keyof T & string]: NonNullable<T[K]> extends object
+           ? readonly [K] | readonly [K, ...Extract<PathL2<NonNullable<T[K]>>, readonly string[]>]
+           : readonly [K];
+     }[keyof T & string]
+   : never;
+
+type PathL2<T> = T extends object
+   ? {
+        [K in keyof T & string]: NonNullable<T[K]> extends object
+           ? readonly [K] | readonly [K, ...Extract<PathL3<NonNullable<T[K]>>, readonly string[]>]
+           : readonly [K];
+     }[keyof T & string]
+   : never;
+
+type PathL3<T> = T extends object
+   ? {
+        [K in keyof T & string]: NonNullable<T[K]> extends object
+           ? readonly [K] | readonly [K, ...Extract<PathL4<NonNullable<T[K]>>, readonly string[]>]
+           : readonly [K];
+     }[keyof T & string]
+   : never;
+
+type PathL4<T> = T extends object
+   ? {
+        [K in keyof T & string]: readonly [K];
+     }[keyof T & string]
+   : never;
+
+/**
+ * Walk a (possibly nested) key path inside the `configuration` subtree
+ * returned by `getConfiguration(root, configuration)`. Returns `undefined`
+ * for any intermediate non-object or missing key — the caller's coercion +
+ * validation then surfaces that as the default.
+ */
+function readKey(subtree: unknown, key: string | readonly string[]): unknown {
+   const segments = typeof key === 'string' ? [key] : key;
+   let current: unknown = subtree;
+   for (const segment of segments) {
+      if (current === null || typeof current !== 'object') {
+         return undefined;
+      }
+      current = (current as Record<string, unknown>)[segment];
+   }
+   return current;
+}
+
+/**
+ * Producers that bind a user-configurable editor setting (an LSP
+ * `workspace/configuration` section) to an {@link ObservableValue} — the
+ * snapshot updates on the initial fetch and on every `didChangeConfiguration`
+ * push for the section. `Settings` is reserved for this user-config source;
+ * the {@link ObservableValue} the producers yield is itself source-agnostic.
+ */
+export namespace Settings {
+   /** Accepted `key` shape for a given `TConfig` (top-level key or nested path tuple). */
+   export type Key<TConfig> = IsUnknown<TConfig> extends true ? string | readonly string[] : (keyof TConfig & string) | Path<TConfig>;
+
+   /**
+    * Construction options for {@link Settings.value}. The two-key shape
+    * (`root` + `configuration`) mirrors Langium's
+    * `ConfigurationProvider.getConfiguration(language, configuration)`: `root`
+    * selects the top-level section (typically the language id), `configuration`
+    * is the first-level key beneath it, and `select` does the deep traversal.
+    */
+   export interface ValueOptions<TConfig, TValue> {
+      readonly services: ServerSharedServices;
+      /**
+       * LSP configuration section root. Defaults to
+       * `services.lsp.configurationRoot`; multi-grammar adopters rebind that
+       * slot to dispatch by language id. Single-grammar adopters rarely pass it.
+       */
+      readonly root?: string;
+      /** First-level key under `root` (NOT a dotted path — Langium semantics). */
+      readonly configuration: string;
+      /**
+       * Default returned until the first fetch completes, and afterwards when
+       * the configuration is absent or `select` returns `undefined` / `null`.
+       */
+      readonly default: TValue;
+      /**
+       * Deep-traverse the subtree returned by `getConfiguration(root,
+       * configuration)`. Returns the typed `TValue`, or `undefined` / `null` /
+       * throws to fall back to {@link ValueOptions.default}.
+       */
+      readonly select: (config: TConfig) => TValue | undefined | null;
+   }
+
+   /**
+    * Bind a {@link ObservableValue} to a Langium configuration section. The
+    * snapshot starts at `default` and updates when (a) the initial
+    * `provider.getConfiguration` resolves and (b) every `didChangeConfiguration`
+    * push affecting the same `root`. `onChange` is dedup'd by snapshot identity
+    * (`Object.is`). Errors thrown by `select` fall back to `default`.
+    */
+   export function value<TConfig, TValue>(options: ValueOptions<TConfig, TValue>): ObservableValue<TValue> {
+      const root = options.root ?? options.services.lsp.configurationRoot;
+      const provider = options.services.workspace.ConfigurationProvider;
+      const emitter = new Emitter<TValue>();
+      let current = options.default;
+
+      const apply = (subtree: unknown): void => {
+         let candidate: TValue | undefined | null;
+         try {
+            candidate = options.select(subtree as TConfig);
+         } catch {
+            candidate = options.default;
+         }
+         const next: TValue = candidate === undefined || candidate === null ? options.default : candidate;
+         if (!Object.is(next, current)) {
+            current = next;
+            emitter.fire(next);
+         }
+      };
+
+      // Initial fetch — `provider.ready` resolves after the client's
+      // `initialized` notification. Failures leave the snapshot at `default`;
+      // it still updates via `onConfigurationSectionUpdate` if pushed later.
+      void provider.ready
+         .then(async () => {
+            const subtree = await provider.getConfiguration(root, options.configuration);
+            apply(subtree);
+         })
+         .catch(() => {
+            // On the CHAIN, not inside the callback: a `ready` rejection is a
+            // failure mode of its own, and a handler that only wraps
+            // `getConfiguration` leaves it as an anonymous unhandled rejection.
+         });
+
+      provider.onConfigurationSectionUpdate(({ section, configuration }: { section: string; configuration: unknown }) => {
+         if (section !== root) {
+            return;
+         }
+         const subtree =
+            configuration === null || typeof configuration !== 'object'
+               ? undefined
+               : (configuration as Record<string, unknown>)[options.configuration];
+         apply(subtree);
+      });
+
+      return {
+         get value(): TValue {
+            return current;
+         },
+         onChange: emitter.event
+      };
+   }
+
+   /**
+    * Common options shared by the typed readers ({@link Settings.number},
+    * {@link Settings.boolean}, {@link Settings.string}). Each binds a value at
+    * `<root>.<configuration>.<key>`. `default` is returned whenever the
+    * configuration is absent, the raw value is the wrong shape, or coercion /
+    * validation rejects it.
+    */
+   export interface ReaderOptions<T, TConfig = unknown> {
+      readonly services: ServerSharedServices;
+      readonly root?: string;
+      readonly configuration: string;
+      /**
+       * Key or path inside the `configuration` subtree. Narrows to the valid
+       * paths through `TConfig` when a schema is declared; otherwise
+       * `string | readonly string[]`.
+       */
+      readonly key: Key<TConfig>;
+      readonly default: T;
+   }
+
+   /** Options for {@link Settings.number}. */
+   export interface NumberOptions<TConfig = unknown> extends ReaderOptions<number, TConfig> {
+      /** Coerce string-typed values via `Number.parseFloat`. Default: `true`. */
+      readonly coerceString?: boolean;
+      /** Reject negative values. Default: `false`. */
+      readonly nonNegative?: boolean;
+      /** Round to the nearest integer via `Math.round`. Default: `false`. */
+      readonly integer?: boolean;
+      /** Reject values below `min`. */
+      readonly min?: number;
+      /** Reject values above `max`. */
+      readonly max?: number;
+   }
+
+   /** Options for {@link Settings.boolean}. */
+   export interface BooleanOptions<TConfig = unknown> extends ReaderOptions<boolean, TConfig> {
+      /** Coerce `'true'`/`'false'`/`'1'`/`'0'` (case-insensitive). Default: `true`. */
+      readonly coerceString?: boolean;
+   }
+
+   /** Options for {@link Settings.string}. */
+   export interface StringOptions<T extends string = string, TConfig = unknown> extends ReaderOptions<T, TConfig> {
+      /** Restrict accepted values to a set. */
+      readonly allowed?: readonly T[];
+      /** Coerce non-string values via `String(value)`. Off by default. */
+      readonly coerceToString?: boolean;
+   }
+
+   /**
+    * Bind a numeric setting with optional string-coercion + range / integer
+    * validation. Any rejection falls back to `default`.
+    */
+   export function number<TConfig = unknown>(options: NumberOptions<TConfig>): ObservableValue<number> {
+      const coerceString = options.coerceString ?? true;
+      return value<unknown, number>({
+         services: options.services,
+         root: options.root,
+         configuration: options.configuration,
+         default: options.default,
+         select: subtree => {
+            const raw = readKey(subtree, options.key);
+            let result: number;
+            if (typeof raw === 'number') {
+               result = raw;
+            } else if (typeof raw === 'string' && coerceString) {
+               result = Number.parseFloat(raw);
+            } else {
+               return undefined;
+            }
+            if (!Number.isFinite(result)) {
+               return undefined;
+            }
+            if (options.nonNegative && result < 0) {
+               return undefined;
+            }
+            if (options.min !== undefined && result < options.min) {
+               return undefined;
+            }
+            if (options.max !== undefined && result > options.max) {
+               return undefined;
+            }
+            return options.integer ? Math.round(result) : result;
+         }
+      });
+   }
+
+   /**
+    * Bind a boolean setting with optional string-coercion (`'true'`/`'false'`/
+    * `'1'`/`'0'`, case-insensitive). Any other shape falls back to `default`.
+    */
+   export function boolean<TConfig = unknown>(options: BooleanOptions<TConfig>): ObservableValue<boolean> {
+      const coerceString = options.coerceString ?? true;
+      return value<unknown, boolean>({
+         services: options.services,
+         root: options.root,
+         configuration: options.configuration,
+         default: options.default,
+         select: subtree => {
+            const raw = readKey(subtree, options.key);
+            if (typeof raw === 'boolean') {
+               return raw;
+            }
+            if (typeof raw === 'string' && coerceString) {
+               const normalised = raw.trim().toLowerCase();
+               if (normalised === 'true' || normalised === '1') {
+                  return true;
+               }
+               if (normalised === 'false' || normalised === '0') {
+                  return false;
+               }
+            }
+            return undefined;
+         }
+      });
+   }
+
+   /**
+    * Bind a string setting with optional non-string coercion + allowed-list
+    * validation. Type-parameterise `T` to a literal-string union to correlate
+    * the snapshot type with the `allowed` set at compile time.
+    */
+   export function string<T extends string = string, TConfig = unknown>(options: StringOptions<T, TConfig>): ObservableValue<T> {
+      const coerceToString = options.coerceToString ?? false;
+      const allowed = options.allowed;
+      return value<unknown, T>({
+         services: options.services,
+         root: options.root,
+         configuration: options.configuration,
+         default: options.default,
+         select: subtree => {
+            const raw = readKey(subtree, options.key);
+            let result: string;
+            if (typeof raw === 'string') {
+               result = raw;
+            } else if (coerceToString && raw !== undefined && raw !== null) {
+               result = String(raw);
+            } else {
+               return undefined;
+            }
+            if (allowed && !allowed.includes(result as T)) {
+               return undefined;
+            }
+            return result as T;
+         }
+      });
+   }
+}
+
+/** Standard LSP message-tracing verbosity — the value of the `<langId>.trace.server` setting. */
+export type TraceServerValue = 'off' | 'messages' | 'verbose';
+
+/**
+ * Shape of the standard `<langId>.trace` configuration section — `trace.server`
+ * selects message-tracing verbosity. The framework owns this type because,
+ * unlike bespoke per-adopter settings, it is universal across LSP adopters: a
+ * server reads it through {@link Settings.string} without re-declaring the
+ * shape, and gets an {@link ObservableValue} that tracks the user's edits.
+ *
+ * **A server usually has nothing to read here, which is why this type has no
+ * in-repo consumer.** The setting is the CLIENT's: `vscode-languageclient`
+ * reads `<clientId>.trace.server` itself, re-reads it on every configuration
+ * change, writes the protocol trace to its own output channel, and forwards the
+ * value to the server as the dedicated `$/setTrace` notification. So the value
+ * already reaches a server on its own channel; going through
+ * `workspace/configuration` is the indirect route to the same thing, and
+ * nothing here registers a `$/setTrace` handler either.
+ *
+ * The one case that wants this type is a server choosing to mirror trace
+ * verbosity onto its own `LogThreshold`. Weigh that deliberately rather than by
+ * analogy: message tracing and application logging are orthogonal axes, so
+ * mirroring means protocol tracing cannot be enabled without also raising
+ * application log volume. The similar spelling is a false friend —
+ * `trace.server: 'verbose'` and `LogThreshold`'s `'trace'` are unrelated.
+ *
+ * The client library does NOT contribute the schema. An adopter that wants the
+ * setting to be discoverable declares it in its own host manifest
+ * (`contributes.configuration`); in Theia that is not merely cosmetic, because
+ * an unregistered preference is dropped as unknown rather than returned.
+ */
+export interface LspTraceConfiguration {
+   server?: TraceServerValue;
+}