@hydranium/protocol 1.0.0-next.10

package/src/tracer.ts

@@ -0,0 +1,277 @@
+/********************************************************************************
+ * 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, SystemClock } from './clock';
+import { Format, Logger, type LogThreshold } from './logger';
+import { NoopLogger } from './noop-logger';
+import { DefaultProfileSession, type ProfileSession } from './profile-session';
+import { Disposable } from './util';
+
+/** Module-global so nested timers don't reuse ids. */
+let nextTimerId = 0;
+
+/** Ops completing before this threshold are silent on success — only failures emit a retroactive start. */
+export const DEFER_START_MS = 5;
+
+/** Optional settings for {@link Tracer.time}. */
+export interface TimeOptions {
+   /** Defer the [start] line until the op has run this long. Set to 0 to always log. */
+   logAfterMs?: number;
+   /** Called with the correlation id before the op runs. */
+   captureId?: (id: number) => void;
+   /** Extra context included in the status brackets. Read on each emit so callers can mutate. */
+   tags?: string[];
+   /** Server-only: force the memory suffix on [done] when elapsed >= this many ms, ignoring the delta gate. */
+   forceMemoryAboveMs?: number;
+}
+
+/** Platform-specific heap readout. Returns `undefined` where unavailable (e.g. a browser outside Chromium). */
+export interface MemoryInfo {
+   /** Bytes currently in use (heap used / `usedJSHeapSize`). */
+   usedBytes: number;
+   /** Optional capacity for a "used / total" rendering (heap total / `totalJSHeapSize`). */
+   totalBytes?: number;
+}
+
+/** Reads the current process/heap memory. The single per-head piece of {@link DefaultTracer}. */
+export type MemoryReader = () => MemoryInfo | undefined;
+
+/**
+ * Cross-head observability handle: everything a {@link Logger} does (emission,
+ * threshold gating, component-prefix derivation) **plus** timing an operation,
+ * reading memory, and opening aggregate {@link ProfileSession}s.
+ *
+ * `Tracer extends Logger` so a service that both logs and times holds a single
+ * handle (`this.tracer.debug(...)` / `this.tracer.time(...)`), and a Tracer is
+ * usable anywhere a Logger is wanted. The emission-only {@link Logger} stays
+ * the lean default for consumers that only log.
+ *
+ * The variance lives in the loggers (per-platform emit sinks); the Tracer
+ * **composes** a Logger and forwards emission to it, so one
+ * {@link DefaultTracer} serves every head with no per-platform subclass. The
+ * {@link for}/{@link sub}/{@link with}/{@link withUri} derivations produce a
+ * child Tracer over the correspondingly-derived logger, so
+ * `tracer.withUri(uri).time(...)` emits through that logger's rendering.
+ */
+export interface Tracer extends Logger {
+   /** Read process/heap memory and emit it as a log line. Platform-specific via {@link MemoryReader}. */
+   memory(label?: string, logLevel?: LogThreshold): void;
+   /**
+    * Run `callback`, emit start / completion / failure with timings. Zero-cost
+    * when `logLevel` is suppressed (incl. `'off'`).
+    *
+    * A success completing under {@link TimeOptions.logAfterMs} is **silent** —
+    * this is "tell me when it is slow", not "record every occurrence". A caller
+    * that wants an unconditional per-occurrence line composes it from
+    * `Clock.measure` instead.
+    */
+   time<T>(label: string, callback: () => T, logLevel?: LogThreshold, options?: TimeOptions): T;
+   /** Start a deferred-start timer that logs elapsed on dispose. Zero-cost when `logLevel` is suppressed (incl. `'off'`). */
+   startTimer(label: string, logLevel?: LogThreshold, logAfterMs?: number): Disposable;
+   /** Open an aggregating self-time {@link ProfileSession} that dumps through the bound Logger. */
+   profile(identifier: string): ProfileSession;
+   /** Derive a child Tracer with `component` as the logger prefix. */
+   for(component: string): this;
+   /** Derive a child Tracer deepening the `Foo :: bar` prefix chain. */
+   sub(component: string): this;
+   /** Derive a child Tracer appending `component` as a separate `[a] [b]` bracket. */
+   with(component: string): this;
+   /** Derive a child Tracer labelled with the given URI (subclasses may render workspace-relative). */
+   withUri(uri: string): this;
+}
+
+/**
+ * Default cross-head {@link Tracer}. One concrete class serves every head:
+ * emission delegates to the composed {@link Logger}, timing/profiling go
+ * through the injected {@link Clock}, and the only per-head varying piece is
+ * the {@link MemoryReader} (default: none — heads that log memory pass a
+ * reader, or subclass for richer rendering, as the server's `ServerTracer`
+ * does). The `time` / `startTimer` bodies are zero-cost when the level is
+ * suppressed: the callback runs directly and no stopwatch / timer / id is
+ * allocated.
+ */
+export class DefaultTracer implements Tracer {
+   constructor(
+      protected readonly logger: Logger = new NoopLogger(),
+      protected readonly clock: Clock = new SystemClock(),
+      protected readonly readMemory: MemoryReader = () => undefined
+   ) {}
+
+   // Emission — forwarded to the composed logger (the platform-specific sink).
+   // Each returns the Tracer (not the wrapped logger) so chained emits stay on
+   // the tracer and `tracer.for(x).trace(y)` yields a Tracer.
+   error(message?: string, ...args: unknown[]): this {
+      this.logger.error(message, ...args);
+      return this;
+   }
+   warn(message?: string, ...args: unknown[]): this {
+      this.logger.warn(message, ...args);
+      return this;
+   }
+   info(message?: string, ...args: unknown[]): this {
+      this.logger.info(message, ...args);
+      return this;
+   }
+   debug(message?: string, ...args: unknown[]): this {
+      this.logger.debug(message, ...args);
+      return this;
+   }
+   trace(message?: string, ...args: unknown[]): this {
+      this.logger.trace(message, ...args);
+      return this;
+   }
+   log(message?: string, ...args: unknown[]): this {
+      this.logger.log(message, ...args);
+      return this;
+   }
+   logAt(threshold: LogThreshold, message: string): this {
+      this.logger.logAt(threshold, message);
+      return this;
+   }
+
+   memory(label?: string, logLevel: LogThreshold = 'info'): void {
+      if (logLevel === 'off' || !Logger.isLevelEnabled(logLevel)) {
+         return;
+      }
+      const info = this.readMemory();
+      if (!info) {
+         // No memory stats available — a contentless "Memory:" line is noise.
+         return;
+      }
+      const used = Format.bytes(info.usedBytes);
+      const text = info.totalBytes !== undefined ? `${used}/${Format.bytes(info.totalBytes)}` : used;
+      this.logger[logLevel](`${label ? `${label}: ` : 'Memory: '}${text}`);
+   }
+
+   time<T>(label: string, callback: () => T, logLevel: LogThreshold = 'info', options: TimeOptions = {}): T {
+      if (logLevel === 'off' || !Logger.isLevelEnabled(logLevel)) {
+         return callback();
+      }
+      const { logAfterMs = DEFER_START_MS, captureId, tags } = options;
+      const id = ++nextTimerId;
+      captureId?.(id);
+      const stopwatch = this.clock.stopwatch();
+      let startEmitted = false;
+      let startTimer: Disposable | undefined;
+      const currentExtras = (): string => (tags && tags.length > 0 ? `, ${tags.join(', ')}` : '');
+      const emitStart = (): void => {
+         this.logger[logLevel](`${label} [#${id} start${currentExtras()}]`);
+         startEmitted = true;
+      };
+      if (logAfterMs <= 0) {
+         emitStart();
+      } else {
+         startTimer = this.clock.setTimer(emitStart, logAfterMs);
+      }
+      const emit = (status: 'done' | 'failed' | 'cancelled', error?: unknown): void => {
+         startTimer?.dispose();
+         if (!startEmitted) {
+            if (status === 'done') {
+               return;
+            }
+            emitStart();
+         }
+         const elapsed = stopwatch.elapsedMs;
+         const suffix = this.timingSuffix(status, elapsed, options);
+         this.logger[logLevel](`${label} [#${id} ${status}, ${Format.elapsed(elapsed)}${currentExtras()}${suffix}]`);
+         if (status === 'failed') {
+            // The timing line above sits at `logLevel`, which may be below the
+            // active threshold — and on its own it never carries *why* the op
+            // failed. Surface the error at warn so the failure is never silent,
+            // with the stack at debug. Cancellations are normal control flow.
+            const detail = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`${label} [#${id}] failed: ${detail}`);
+            if (error instanceof Error && error.stack) {
+               this.logger.debug(error.stack);
+            }
+         }
+      };
+      let result: T;
+      try {
+         result = callback();
+      } catch (error) {
+         emit(this.categorizeError(error), error);
+         throw error;
+      }
+      if (result instanceof Promise) {
+         return result.then(
+            value => {
+               emit('done');
+               return value;
+            },
+            error => {
+               emit(this.categorizeError(error), error);
+               throw error;
+            }
+         ) as T;
+      }
+      emit('done');
+      return result;
+   }
+
+   startTimer(label: string, logLevel: LogThreshold = 'info', logAfterMs: number = DEFER_START_MS): Disposable {
+      if (logLevel === 'off' || !Logger.isLevelEnabled(logLevel)) {
+         return Disposable.create(() => {});
+      }
+      const id = ++nextTimerId;
+      const stopwatch = this.clock.stopwatch();
+      let startEmitted = false;
+      let startTimer: Disposable | undefined;
+      const emitStart = (): void => {
+         this.logger[logLevel](`${label} [#${id} start]`);
+         startEmitted = true;
+      };
+      if (logAfterMs <= 0) {
+         emitStart();
+      } else {
+         startTimer = this.clock.setTimer(emitStart, logAfterMs);
+      }
+      return Disposable.create(() => {
+         startTimer?.dispose();
+         if (!startEmitted) {
+            return;
+         }
+         const elapsed = stopwatch.elapsedMs;
+         const suffix = this.timingSuffix('done', elapsed, {});
+         this.logger[logLevel](`${label} [#${id} done, ${Format.elapsed(elapsed)}${suffix}]`);
+      });
+   }
+
+   profile(identifier: string): ProfileSession {
+      return new DefaultProfileSession(this.logger, this.clock, identifier);
+   }
+
+   for(component: string): this {
+      return this.derive(this.logger.for(component));
+   }
+   sub(component: string): this {
+      return this.derive(this.logger.sub(component));
+   }
+   with(component: string): this {
+      return this.derive(this.logger.with(component));
+   }
+   withUri(uri: string): this {
+      return this.derive(this.logger.withUri(uri));
+   }
+
+   /** Construct a sibling Tracer over a derived logger, preserving the concrete subclass. */
+   protected derive(logger: Logger): this {
+      return new DefaultTracer(logger, this.clock, this.readMemory) as this;
+   }
+
+   /** Hook for appending status-bracket suffixes like memory deltas. Default: none. */
+   protected timingSuffix(_status: 'done' | 'failed' | 'cancelled', _elapsedMs: number, _options: TimeOptions): string {
+      return '';
+   }
+
+   /** Hook to differentiate cancelled operations from failures. Default: all errors are failures. */
+   protected categorizeError(_error: unknown): 'failed' | 'cancelled' {
+      return 'failed';
+   }
+}

package/src/transfer-diagnostic.ts

@@ -0,0 +1,92 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Generic, transport-friendly diagnostic shape used by the model-server protocol.
+ *
+ * The `element` path is a `/`-separated location string with `@` and `^` as index
+ * and property separators, matching the conventions used by Langium's
+ * `AstNodeLocator` service.
+ */
+export interface TransferDiagnostic {
+   /**
+    * Which stage produced it. Coarse by construction: only the two syntactic
+    * stages are recognised by name and everything else — a framework integrity
+    * rule, an adopter check, a linker failure — arrives as `validation-error`.
+    * Use it to decide whether the document PARSED, not to identify a rule.
+    */
+   type: 'lexing-error' | 'parsing-error' | 'validation-error';
+   /**
+    * `AstNodeLocator`-style path to the offending node. **Empty string when the
+    * diagnostic carries no location** — the framework's own validator decorates
+    * every diagnostic, but a rebound one need not, and an empty path denotes
+    * "unlocated" rather than the document root.
+    */
+   element: string;
+   /**
+    * Names the offending property when the diagnostic is about one; absent when
+    * it is about the node as a whole. Append it to {@link element} with
+    * `ELEMENT_PROPERTY_SEPARATOR` rather than by hand — `getPath` does exactly
+    * that and handles the absent case.
+    */
+   property?: string;
+   /**
+    * Plain text, always. An LSP `MarkupContent` message is flattened on the way
+    * out, so no markup survives the wire and a consumer must not try to render
+    * it as rich text.
+    */
+   message: string;
+   /**
+    * Three levels against LSP's four: `Hint` and `Information` both arrive as
+    * `info`, so a client cannot recover the distinction. Anything that is not
+    * an error or a warning lands in `info`, including a diagnostic that carried
+    * no severity at all.
+    */
+   severity: 'error' | 'warning' | 'info';
+   /**
+    * The diagnostic's own code where it has one, otherwise Langium's internal
+    * code — which means it may simply restate {@link type} for a syntactic
+    * error. Absent when neither exists, and not unique across languages, so it
+    * is not usable as a rule identity on its own.
+    */
+   code?: number | string;
+}
+
+export namespace TransferDiagnostic {
+   /** Path separator between AST nodes within an element location. */
+   export const ELEMENT_SEGMENT_SEPARATOR = '/';
+   /** Index separator within an array property segment. */
+   export const ELEMENT_INDEX_SEPARATOR = '@';
+   /** Property separator suffixing the element path with the offending property name. */
+   export const ELEMENT_PROPERTY_SEPARATOR = '^';
+
+   export function isError(diagnostic: TransferDiagnostic): boolean {
+      return diagnostic.severity === 'error';
+   }
+
+   export function isParseError(diagnostic: TransferDiagnostic): boolean {
+      return diagnostic.type === 'parsing-error';
+   }
+
+   export function getPath(diagnostic: TransferDiagnostic): string {
+      return diagnostic.property ? `${diagnostic.element}${ELEMENT_PROPERTY_SEPARATOR}${diagnostic.property}` : diagnostic.element;
+   }
+
+   export function errors(diagnostics: TransferDiagnostic[]): TransferDiagnostic[] {
+      return diagnostics.filter(isError);
+   }
+
+   export function hasErrors(diagnostics: TransferDiagnostic[]): boolean {
+      return diagnostics.some(isError);
+   }
+
+   export function hasParseErrors(diagnostics: TransferDiagnostic[]): boolean {
+      return diagnostics.some(isParseError);
+   }
+}

package/src/transfer-document.ts

@@ -0,0 +1,99 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { TransferDiagnostic } from './transfer-diagnostic';
+import type { TransferElement } from './transfer-element';
+
+/**
+ * Wire envelope exchanged between the model-server's data-server head and
+ * its clients. Carries a transfer-shaped root — never an AST root — plus
+ * the document's diagnostics in the adopter's wire-diagnostic shape.
+ *
+ * The constraint `TTransfer extends TransferElement` pins the type system
+ * to the wire data shape (no `$container` cycles, references as strings;
+ * see {@link TransferElement}). The paired server-internal envelope is
+ * `AstDocument<TAst extends AstNode, TDiagnostic>` in
+ * `@hydranium/core` — same structural shape, different generic
+ * constraint, used at the AST layer before the `TransferEncoder`
+ * translation produces a {@link TransferDocument}.
+ */
+export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> {
+   uri: string;
+   /**
+    * The document version this snapshot was taken at — sourced from the
+    * server's text-document version counter. Callers that mutate the
+    * document subsequently pass this value back as `TransferUpdateArgs.baseVersion`
+    * (or `TransferSaveArgs.baseVersion`) so the server can detect stale-based
+    * updates and reject them with `ConflictError`.
+    *
+    * See `@hydranium/protocol#errors` for the conflict-detection contract.
+    */
+   version: number;
+   /**
+    * Absent when the document does not exist — the server answers an unknown URI
+    * with a shaped envelope rather than an error, so absence is an ordinary
+    * branch and not a catch. Declared required it reads as a guarantee, and
+    * every `root.x` compiles into a throw.
+    */
+   root?: TTransfer;
+   diagnostics: TDiagnostic[];
+}
+
+/**
+ * A {@link TransferDocument} the server actually had, so `root` is present.
+ * Narrowed to by {@link TransferDocument.isLoaded} / {@link TransferDocument.assertLoaded}.
+ */
+export type LoadedTransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> = TransferDocument<
+   TTransfer,
+   TDiagnostic
+> & {
+   root: TTransfer;
+};
+
+export namespace TransferDocument {
+   /**
+    * Whether the server had this document. Branch on it where absence is an
+    * ordinary state — a view bound to a file that may not exist yet.
+    */
+   export function isLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      document: TransferDocument<TTransfer, TDiagnostic>
+   ): document is LoadedTransferDocument<TTransfer, TDiagnostic> {
+      return document.root !== undefined;
+   }
+
+   /**
+    * The same document with `root` no longer optional, or a throw. For call
+    * sites where absence is a bug rather than a branch; the whole envelope is
+    * returned because a caller needing `root` usually needs `uri` or `version`
+    * with it.
+    */
+   export function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      document: TransferDocument<TTransfer, TDiagnostic>
+   ): LoadedTransferDocument<TTransfer, TDiagnostic> {
+      if (!isLoaded(document)) {
+         throw new Error(`No document at ${document.uri}`);
+      }
+      return document;
+   }
+
+   /**
+    * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
+    * to `[]` so test fixtures, fake protocol implementations, and the
+    * "no diagnostics yet" code paths don't need to repeat the empty array
+    * at every call site.
+    */
+   export function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      uri: string,
+      version: number,
+      root: TTransfer,
+      diagnostics: TDiagnostic[] = []
+   ): TransferDocument<TTransfer, TDiagnostic> {
+      return { uri, version, root, diagnostics };
+   }
+}

package/src/transfer-element.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * Copyright (c) 2023-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
+ ********************************************************************************/
+
+/**
+ * Base shapes for the transfer-model overlay generated per consumer language.
+ *
+ * Every node in a generated transfer model extends {@link TransferElement} and
+ * cross-references between nodes serialise as plain strings. These types carry no
+ * language-specific knowledge — language-specific types live in the consumer's
+ * generated `transfer-model.ts` overlay, emitted by the code generator from
+ * the consumer's grammar.
+ */
+
+/** Base type of every transfer-model node — carries the AST type discriminator. */
+export interface TransferElement {
+   readonly $type: string;
+}
+
+/**
+ * Type-level lookup: given an AST node type `T` (with a string-literal
+ * `$type` discriminator from Langium's generated AST) and a per-grammar
+ * `TTransferMap` overlay keyed by those `$type` strings, resolve to the
+ * declared wire shape — or fall back to the structural base
+ * {@link TransferElement} when no entry is declared.
+ *
+ * Adopters declare the overlay by interface merging or by generating an
+ * interface keyed on those `$type` strings. Types not in the overlay resolve to
+ * `TransferElement` — the framework default behaves correctly without an
+ * overlay (no autocomplete, but no compile error either).
+ *
+ * The lookup is compile-time only; no runtime cost.
+ */
+export type TransferTypeFor<TAst extends { readonly $type: string }, TTransferMap> = TAst['$type'] extends keyof TTransferMap
+   ? TTransferMap[TAst['$type']] extends TransferElement
+      ? TTransferMap[TAst['$type']]
+      : TransferElement
+   : TransferElement;

package/src/uri.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Branded URI-string types distinguishing the framework's two document-identity
+ * spaces. Both are `string` at runtime — the brand is a phantom field, erased by
+ * the compiler, so there is zero runtime cost and the values pass freely to any
+ * `string` sink (`UriUtils`, RPC payloads, logs). At compile time they are
+ * **nominally distinct and mutually non-assignable**, so one cannot be used
+ * where the other is expected.
+ *
+ * - {@link CanonicalUri} — *server-identity* space: the single canonical key a
+ *   document is stored under (`LangiumDocuments` keying, AST-document event
+ *   filters, request-path lookups). Minted ONLY by
+ *   `DocumentUriPolicy.canonicalUri` — the single point that defines what
+ *   "canonical" means, so every `CanonicalUri` has provable provenance.
+ * - {@link LanguageClientUri} — the URI the LSP *textual* language client
+ *   (Monaco / VS Code) actually opened a document under, which may differ from
+ *   its canonical identity (e.g. a symlinked path while the document is keyed by
+ *   its real path). This is the URI `applyEditToLanguageClient` and diagnostics must
+ *   address. Named for the *language client* specifically — the GLSP and
+ *   data-server heads are also clients, but they are addressed canonically.
+ *
+ * Why both are real brands rather than aliases: a plain `type X = string` is
+ * assignable to and from any `string` (and a `CanonicalUri` *is* a `string`), so
+ * an alias would let a canonical URI flow into a language-client sink unchecked —
+ * exactly the class of bug where an outbound sync addressed the client by the
+ * canonical URI it never opened. The distinct `__uriSpace` discriminants make
+ * that a compile error, and make plain `string` assignable to neither — forcing
+ * values through a mint point.
+ *
+ * Scope: these are an **internal** server-identity discipline. RPC/wire fields
+ * and public service parameters stay plain `string` so the brands never leak to
+ * adopters or across the wire; conversion happens at the framework boundary.
+ */
+export type CanonicalUri = string & { readonly __uriSpace: 'canonical' };
+
+/** The LSP textual language client's document URI. See {@link CanonicalUri} for the full rationale. */
+export type LanguageClientUri = string & { readonly __uriSpace: 'languageClient' };
+
+/**
+ * Mint a {@link CanonicalUri}. The single sanctioned place the brand assertion
+ * lives — call this from the one component that defines canonicalisation
+ * (`DocumentUriPolicy.canonicalUri`) instead of scattering `as CanonicalUri`
+ * casts, so a call site reads as a deliberate identity mint rather than an
+ * escape hatch.
+ */
+export const asCanonicalUri = (value: string): CanonicalUri => value as CanonicalUri;
+
+/**
+ * Mint a {@link LanguageClientUri}. The single sanctioned place the brand
+ * assertion lives — call this from the component that owns the language-client
+ * URI space (the text store's `toLanguageClientUri`). See {@link asCanonicalUri}.
+ */
+export const asLanguageClientUri = (value: string): LanguageClientUri => value as LanguageClientUri;