@hydranium/protocol 1.0.0-next.30 → 1.0.0-next.301

package/src/logger.ts

@@ -24,6 +24,7 @@ export const LEVEL_LABELS: Record<LogLevel, string> = {
 /** Module-global threshold; shared by every `AbstractLogger` instance so derived child
  *  loggers pick up live updates without each having to subscribe to a configuration source. */
 let currentLevel: LogThreshold = 'info';
+let fileLevel: LogThreshold | undefined;
 
 /**
  * Cross-side public logger contract. Every consumer of the framework — browser
@@ -38,15 +39,15 @@ let currentLevel: LogThreshold = 'info';
  * and every `for` / `sub` / `with` derivation preserves the implementation type.
  */
 export interface Logger {
-   /** Log a message at error level. */
+   /** Requested work failed; logged once, by the code that ends the failure, not by one that rethrows it. */
    error(message?: string, ...args: unknown[]): this;
-   /** Log a message at warn level. */
+   /** An anomaly that was handled, or work declined by design, such as a conflict or a cap; a clean run logs none. */
    warn(message?: string, ...args: unknown[]): this;
-   /** Log a message at info level. */
+   /** A milestone the person running the server would recognise without knowing the internals. */
    info(message?: string, ...args: unknown[]): this;
-   /** Log a message at debug level. */
+   /** Diagnosis; its level decides whether the line is built, never which code runs. */
    debug(message?: string, ...args: unknown[]): this;
-   /** High-volume diagnostic lines, only emitted at the `'trace'` threshold. */
+   /** High-volume diagnosis, emitted only at the `'trace'` threshold; as for `debug`, no code runs only for it. */
    trace(message?: string, ...args: unknown[]): this;
    /** Log a message at info-level threshold with a `Log` label (rather than `Info`). */
    log(message?: string, ...args: unknown[]): this;
@@ -93,12 +94,32 @@ export namespace Logger {
       return currentLevel;
    }
    /**
-    * Whether a message at `level` would be emitted at the current threshold.
+    * Set the log file's own threshold, which {@link setLevel} does not move;
+    * `undefined` makes the file follow {@link getLevel}. A file sink compares
+    * against `getFileLevel() ?? getLevel()`, every other sink against
+    * {@link getLevel}.
+    *
+    * Set it through the file sink's own configuration, which clears it with
+    * the file: set here with no file configured, it widens
+    * {@link isLevelEnabled} for lines nothing writes.
+    */
+   export function setFileLevel(level: LogThreshold | undefined): void {
+      fileLevel = level;
+   }
+   /** Read the log file's own threshold, `undefined` while it follows {@link getLevel}. */
+   export function getFileLevel(): LogThreshold | undefined {
+      return fileLevel;
+   }
+   /**
+    * Whether any sink takes a message at `level`: the more verbose of
+    * {@link getLevel} and {@link getFileLevel} decides. A sink that admits less
+    * re-checks its own threshold before writing.
+    *
     * Use to guard expensive log-line construction:
     * `if (Logger.isLevelEnabled('trace')) logger.trace(buildPayload())`.
     */
    export function isLevelEnabled(level: LogLevel): boolean {
-      return LEVEL_ORDER[level] <= LEVEL_ORDER[currentLevel];
+      return LEVEL_ORDER[level] <= Math.max(LEVEL_ORDER[currentLevel], fileLevel ? LEVEL_ORDER[fileLevel] : 0);
    }
    /**
     * Whether a message at `threshold` would be emitted: `false` for `'off'`,
@@ -134,8 +155,23 @@ export function parseLogLevel(value: unknown): LogThreshold | undefined {
  * instead of duplicating the literal string.
  */
 export const DEFAULT_LOG_LEVEL_ENV = 'HYDRANIUM_LOG_LEVEL';
-/** Env var the server reads its log file-tee target from. See {@link DEFAULT_LOG_LEVEL_ENV}. */
+/**
+ * Env var the server reads its log file-tee target from. The path may hold
+ * `{workspace}`, filled in once the server knows its workspace, and `{pid}`.
+ * See {@link DEFAULT_LOG_LEVEL_ENV}.
+ */
 export const DEFAULT_LOG_FILE_ENV = 'HYDRANIUM_LOG_FILE';
+/**
+ * Env var the server reads the file tee's own threshold from, which the LSP
+ * log-level setting does not change. See {@link Logger.setFileLevel}.
+ */
+export const DEFAULT_LOG_FILE_LEVEL_ENV = 'HYDRANIUM_LOG_FILE_LEVEL';
+/**
+ * Env var naming the file a Node server writes its CPU profile to when it
+ * ends. Takes `{workspace}` and `{pid}` as {@link DEFAULT_LOG_FILE_ENV} does;
+ * the write replaces the file, so `{pid}` keeps one per server.
+ */
+export const DEFAULT_CPU_PROFILE_FILE_ENV = 'HYDRANIUM_CPU_PROFILE_FILE';
 
 /**
  * Human-readable formatting helpers used in log lines and diagnostic output.

package/src/messages/index.ts

@@ -25,8 +25,10 @@
 
 export * from './primitives';
 
-export { STALE_BASED_UPDATE } from '../errors';
-export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/data-session';
+export { DOCUMENT_NOT_OPEN, DUPLICATE_CLIENT_ID, SESSION_CLOSED, STALE_BASE_VERSION_UPDATE } from '../errors';
+export { DATA_CONNECTION_SESSION_RESTORE_FAILED, DATA_CONNECTION_WATCH_RESTORE_FAILED } from '../client/data-connection';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export { DATA_SESSION_ANSWER_WITHOUT_MODEL, DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
 export {
    RELAY_REPLAY_FAILED,
    RELAY_TRANSPORT_OPEN_FAILED,

package/src/messages/primitives.ts

@@ -10,12 +10,18 @@
 import { ResponseError } from 'vscode-jsonrpc';
 
 /**
- * The framework externalizes user-facing strings and never translates them: it
- * holds no locale, so it cannot know what the reading user reads. Every such
- * string carries a stable code beside its English text, and whoever owns the
- * surface renders it. A framework-held locale would give one toast two
- * authorities — an adopter sentence in one language wrapping a framework clause
- * in another.
+ * The framework externalizes user-facing strings and SELECTS no locale: it
+ * relays the one its client declared and renders with whatever templates the
+ * adopter installed, defaulting to its English. Every such string carries a
+ * stable code beside that English, and exactly one side renders it — the side
+ * that knows the reading user's language.
+ *
+ * Which side that is depends on the message, not on the package. A server
+ * message is rendered by the server, at the one seam every carrier passes
+ * through, in the locale it was handed at init. A message the client tier raises
+ * is rendered there, because those fire when the server is unreachable. Nothing
+ * is rendered twice: two renders of one sentence are two authorities over it,
+ * and they diverge on the first reword.
  *
  * Codes are `hydranium/<unscoped-package>/<name>`. The package segment locates
  * the declaration, so a message is declared in the package that raises it and a
@@ -156,11 +162,67 @@ export function messageError<S extends string>(
 }
 
 /**
- * Render on the side that knows the reading user's locale. `translations` is
- * whatever flat `code → template` map the host exposes; omitting it is how an
- * adopter without i18n opts out, and yields the English.
+ * The reading user's language, as the tag a client declared.
+ *
+ * Neither validated nor normalised anywhere: rejecting an unfamiliar tag would
+ * be selecting a locale, which the framework does not do.
+ *
+ * NOT a Langium language id, which names a grammar. The two are strings of the
+ * same shape reachable from the same services, so one used where the other
+ * belongs misses every lookup rather than failing.
+ */
+export type Locale = string;
+
+/**
+ * A host's templates for one locale, keyed by the whole message code.
+ *
+ * **Flat, not nested.** A code is one key here, `/` separators included; a host
+ * whose own catalogue format nests — Theia's does — flattens on the way in. A
+ * map that nests instead misses every lookup while type-checking, because the
+ * value this is indexed by is `ResolvedMessage.code`.
+ *
+ * **Partial by nature rather than by convention.** A code with no entry renders
+ * its English default, so a catalogue covering none of a package's codes is a
+ * valid catalogue and not a broken one — which is what lets an adopter translate
+ * as much or as little as they like.
+ *
+ * Deliberately NOT narrowed to the codes that exist, and a `Code extends string`
+ * parameter would not buy what it appears to: a catalogue is loaded as JSON, so
+ * it reaches a checked position as a variable rather than as an object literal,
+ * and excess-property checking — the only thing that would reject a mistyped
+ * key — does not run there. The gain is a compile error for a catalogue with no
+ * correct key at all; the cost is a code union to maintain by hand, since a
+ * declaration does not carry its code as a literal type.
+ */
+export type MessageCatalogue = Readonly<Record<string, string>>;
+
+export namespace MessageCatalogue {
+   /**
+    * One catalogue from several, for a renderer whose override supplies entries
+    * over the ones it inherits.
+    *
+    * **Later wins**, so a caller passes the inherited answer before its own.
+    *
+    * **No source at all answers `undefined`, not `{}`.** A renderer holds that
+    * answer as the locale having no catalogue and renders straight through; an
+    * empty object is a catalogue that misses every lookup, so returning one
+    * turns the opt-out into a per-message search that yields the same English.
+    */
+   export function merge(...catalogues: ReadonlyArray<MessageCatalogue | undefined>): MessageCatalogue | undefined {
+      const present = catalogues.filter((catalogue): catalogue is MessageCatalogue => catalogue !== undefined);
+      if (present.length <= 1) {
+         return present[0];
+      }
+      return Object.assign({}, ...present) as MessageCatalogue;
+   }
+}
+
+/**
+ * Render on the side that knows the reading user's locale. Omitting
+ * `translations` is how an adopter without i18n opts out, and yields the
+ * English.
  */
-export function renderFrameworkMessage(message: ResolvedMessage, translations?: Record<string, string>): string {
+export function renderFrameworkMessage(message: ResolvedMessage, translations?: MessageCatalogue): string {
    const template = translations?.[message.code];
    return template ? interpolate(template, message.params) : message.text;
 }
@@ -174,11 +236,41 @@ export function resolvedFromResponseError(error: ResponseError<unknown>): Resolv
  * to pass as a parameter for the same reason a number is: it is not itself
  * translatable text, so it needs no code of its own. A PROSE fragment is not,
  * and must become one code per value instead.
+ *
+ * For a reader of the client; the log takes {@link describeErrorWithStack}.
  */
 export function describeError(error: unknown): string {
    return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * An error for the log: its stack where it has one, which names where it was
+ * thrown, and its causes, which name what failed when an error wraps another.
+ * Never for the client, whose reader cannot act on a stack.
+ */
+export function describeErrorWithStack(error: unknown): string {
+   // A cause chain may loop back on itself.
+   return describeChain(error, new Set());
+}
+
+function describeChain(error: unknown, seen: Set<unknown>): string {
+   const lines: string[] = [];
+   let current: unknown = error;
+   let prefix = '';
+   do {
+      seen.add(current);
+      lines.push(prefix + (current instanceof Error ? (current.stack ?? current.message) : String(current)));
+      // Node fails a connect to several addresses with one, whose own message is empty.
+      if (current instanceof AggregateError) {
+         const errors: unknown[] = current.errors;
+         lines.push(...errors.filter(inner => !seen.has(inner)).map(inner => `Including: ${describeChain(inner, seen)}`));
+      }
+      current = current instanceof Error ? current.cause : undefined;
+      prefix = 'Caused by: ';
+   } while (current !== undefined && current !== null && !seen.has(current));
+   return lines.join('\n');
+}
+
 /**
  * Recognises a declaration among a barrel's exports. The `format` check is what
  * discriminates: a `code` + `text` pair alone admits any object that happens to

package/src/model-server.ts

@@ -14,17 +14,19 @@
  * over `TRoot`.
  */
 
-import type { TransferClientArgs } from './model-service/args';
 import type { ReferenceCandidate } from './model-service/reference-candidate';
 
 // ---------------------------------------------------------------------------
 // Client / server arguments
 // ---------------------------------------------------------------------------
 
-// `TransferClientArgs` / `TransferUpdateArgs` / `TransferSaveArgs` live in
-// `./model-service/args.ts` and are re-exported by the main barrel via
-// `./model-service`. The legacy LSP-style protocol (Open / Close / events)
-// defined here only consumes them as a supertype.
+/** Identifies a client-document binding. */
+export interface TransferClientArgs {
+   /** Document URI. */
+   uri: string;
+   /** Stable identifier for the client invoking the operation. */
+   clientId: string;
+}
 
 /** Open a document on behalf of a client. */
 export interface OpenModelArgs extends TransferClientArgs {
@@ -47,14 +49,22 @@ export interface OpenModelArgs extends TransferClientArgs {
     * means read from the filesystem, which is the normal case.
     *
     * Honoured only on the first open of a URI: opening an already-open document
-    * is a no-op, so passing `text` for one silently changes nothing. Write
-    * through the update path instead.
+    * attaches the caller to the existing shared entry and does not replace its
+    * content with this seed. Write through the update path instead. The open
+    * response reads the current shared content after registration; a textual
+    * `didOpen` attach may separately refresh the build.
     */
    text?: string;
+   /**
+    * Kept on the server for this client's open until it closes, for the
+    * server's own open path to read. Only a client session's open keeps them,
+    * and a repeat open keeps the first open's.
+    */
+   options?: object;
 }
 
 /** Close a previously-opened document for the client. */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- close names its own args; it adds no field to the base
 export interface CloseModelArgs extends TransferClientArgs {}
 
 // ---------------------------------------------------------------------------
@@ -63,9 +73,25 @@ export interface CloseModelArgs extends TransferClientArgs {}
 
 export interface TransferUpdatedEvent<TDocument> {
    document: TDocument;
+   /**
+    * The client whose write this event echoes: the author of the version on a
+    * `'changed'`, and the unknown-client id on a `'rebuilt'`, which echoes no
+    * write. A recipient compares it against its own id to recognise its echo.
+    */
    sourceClientId: string;
-   /** See `ModelDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
-   reason: 'changed' | 'deleted' | 'rebuilt' | 'saved';
+   /** See `TransferDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
+   reason: 'changed' | 'rebuilt' | 'saved';
+   /**
+    * The client whose write caused the build that produced this event, or the
+    * unknown-client id when no single client's did. On a `'changed'` it is the
+    * version's author. A `'rebuilt'` names the writer of another document, so
+    * it is a cause, never an echo: its diagnostics and references are new to
+    * that writer too.
+    *
+    * In-process only: the data head does not send it, and an event built
+    * elsewhere may leave it out, which a reader takes as "not known".
+    */
+   causedBy?: string;
 }
 
 export interface TransferSavedEvent<TDocument> {
@@ -147,10 +173,10 @@ export function isElementSource(object: unknown): object is ElementSource {
 /** An element of a document that does not yet exist on disk — used during element creation flows. */
 export interface SyntheticSource {
    /**
-    * The document the element would belong to. That document must already be
-    * LOADED — the default resolution takes its parse root as the synthetic
-    * node's container and answers `undefined` when it is not, so a URI for a
-    * file that exists on disk but was never opened resolves to nothing.
+    * The document the element would belong to. It need not be loaded, or
+    * exist — an unloaded URI materialises a transient empty document, so a
+    * folder is a valid anchor. A URI that IS loaded contributes that
+    * document's parse root as the container, putting its contents in scope.
     */
    uri: string;
    /**
@@ -159,6 +185,16 @@ export interface SyntheticSource {
     * it is what scoping filters candidates against.
     */
    type: string;
+   /**
+    * The grammar the element will belong to, as a language id.
+    *
+    * Optional because `uri` and `type` each answer on their own when
+    * unambiguous. Set it when neither is: a URI naming no file carries no
+    * extension to route on, and a `type` two grammars can produce identifies
+    * neither. Unset, such a source reaches the server's own policy, which
+    * answers the same way for every caller.
+    */
+   language?: string;
 }
 
 export function isSyntheticSource(object: unknown): object is SyntheticSource {
@@ -183,8 +219,10 @@ export namespace ReferenceSource {
    export function element(name: string, type?: string): ElementSource {
       return { name, type };
    }
-   export function synthetic(uri: string, type: string): SyntheticSource {
-      return { uri, type };
+   export function synthetic(uri: string, type: string, language?: string): SyntheticSource {
+      // The key is omitted rather than set to `undefined`, so a source built
+      // without a language stays deep-equal to the two-argument form.
+      return language === undefined ? { uri, type } : { uri, type, language };
    }
 }
 
@@ -457,9 +495,10 @@ export interface FindNextNameArgs {
     */
    uri: string;
    /**
-    * The AST `$type` of the element being named. Collisions are only looked for
-    * among elements of that same type, so the returned name may still be taken
-    * by an element of another type.
+    * The AST `$type` of the element being named. Collisions are looked for
+    * among elements of that type and of any subtype of it, so a supertype
+    * names a uniqueness scope its concrete types share; the returned name may
+    * still be taken by an element outside that hierarchy.
     */
    type: string;
    /**
@@ -476,4 +515,10 @@ export interface FindNextNameArgs {
     * See {@link NameTier} for what each tier covers.
     */
    tier?: NameTier;
+   /**
+    * The grammar to name under, routed as {@link SyntheticSource.language} —
+    * this call builds one. A caller that sets it there must set it here, or
+    * candidates and the name it proposes come from different grammars.
+    */
+   language?: string;
 }

package/src/model-service/base-version.ts

@@ -0,0 +1,75 @@
+/********************************************************************************
+ * Copyright (c) 2026 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
+ ********************************************************************************/
+
+declare const snapshotMarker: unique symbol;
+
+/**
+ * The version of the text a model was parsed from: a snapshot of the store's
+ * {@link TextVersion}, not a counter of its own. A document envelope carries
+ * it, and it cannot move once the envelope exists. A create's answer carries
+ * a second snapshot of the same kind, the version the create's text took,
+ * which its creator holds because it sent the text.
+ *
+ * A plain number at runtime, usable anywhere a number is, and it travels the
+ * wire as one. The marker exists only so the compiler can tell it apart from a
+ * version read off a LIVE document, which is the same number type and is the
+ * defect the conflict gate exists to prevent: read at write time it is whatever
+ * the server is at now, which is the number the gate is about to compare it
+ * against, so the gate passes unconditionally and a concurrent edit is
+ * overwritten with nothing logged.
+ */
+export type ModelVersion = number & { readonly [snapshotMarker]: true };
+
+/**
+ * The store's version of a document's text, which moves with every change of it.
+ * Unbranded, so a write refuses it as `baseVersion`: it can name text newer than
+ * the caller's model, and a write based on it would pass the gate with older content.
+ */
+export type TextVersion = number;
+
+/**
+ * The version a write was authored against, from a snapshot read, or `'any'`: a
+ * precondition that always holds, so the write overwrites whatever the server has.
+ * `'any'` is a lie for a write authored against a document a read handed over.
+ */
+export type BaseVersion = ModelVersion | 'any';
+
+/** Whether `baseVersion` names a version, and so arms the gate. */
+export function isModelVersion(baseVersion: BaseVersion): baseVersion is ModelVersion {
+   return typeof baseVersion === 'number';
+}
+
+/**
+ * Mark a version as having come from a snapshot read.
+ *
+ * **For the envelope constructors, not for callers.** Every door that builds a
+ * document envelope applies it on the way in, the create's answer included
+ * for the version its text took, so anything a read returns already carries
+ * it and a writer never needs this. A caller reaching for it is
+ * asserting a provenance the compiler was about to deny — the read-late defect
+ * written out where a reviewer can see it.
+ */
+export function asModelVersion(version: number): ModelVersion {
+   return version as ModelVersion;
+}
+
+/**
+ * The model version of a root no document factory path built, so nothing
+ * records the text it came from. No write matches it, so a write based on it
+ * conflicts.
+ */
+export const UNRECORDED_VERSION: ModelVersion = asModelVersion(-2);
+
+/**
+ * The model version of a root parsed from text the store holds under no
+ * version: the file, read while the store held the document open with other
+ * text. Below every text version, so the model reads as behind and a write
+ * based on it conflicts.
+ */
+export const STALE_VERSION: ModelVersion = asModelVersion(-1);

package/src/model-service/index.ts

@@ -7,10 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-// Subpath barrel for the in-process `ModelService` facade contract. The
-// implementation lives in `@hydranium/core`; this package owns the
-// argument types so both the framework facade and the data-server wire
-// protocol can structurally agree on the lifecycle shape.
+// Generic payload types the data protocol shares with core: the base
+// version, which the server's model service checks writes against, and the
+// reference candidates, which core's scope and completion code produce.
 
-export * from './args';
+export * from './base-version';
 export * from './reference-candidate';

package/src/model-service/reference-candidate.ts

@@ -50,9 +50,11 @@ export interface ReferenceCandidate {
  * node's subtree, NOT the whole document root — callers that want the full
  * document fetch it via `getModelDocument(uri)`.
  *
- * Generic over the transfer root type so adopters get their typed overlay.
+ * `TElement` is the type of the target node, not of a document root. A server
+ * answers with the structural base, since a reference can name any node; a
+ * caller that knows what the reference targets may narrow it.
  */
-export interface ReferenceTarget<TTransfer extends TransferElement = TransferElement> extends ReferenceCandidate {
+export interface ReferenceTarget<TElement extends TransferElement = TransferElement> extends ReferenceCandidate {
    /** The resolved target node, encoded as a transfer subtree. */
-   element: TTransfer;
+   element: TElement;
 }

package/src/node/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/protocol/node` — the diagnostics helpers that
+// need a Node runtime, kept out of the root barrel so the root stays
+// bundleable for a browser.
+
+export * from './process-memory';