@hydranium/protocol 1.0.0-next.31 → 1.0.0-next.315

package/src/testing/wait-for.ts

@@ -33,13 +33,19 @@ export interface WaitForOptions {
    readonly timeoutMs?: number;
    /** Poll the predicate every this-many milliseconds. Default 5. */
    readonly intervalMs?: number;
-   /** Error message on timeout. Default a generic phrasing. */
-   readonly message?: string;
+   /**
+    * Error message on timeout, and when the predicate throws. A function is
+    * called only then, so it can report the state the wait ended on; when it
+    * throws, the default text is used, with its throw as the error's `cause`
+    * unless the predicate threw. Default a generic phrasing.
+    */
+   readonly message?: string | (() => string);
 }
 
 /**
  * Resolve once `predicate()` returns true, polling at `intervalMs`; reject with
- * `message` once `timeoutMs` elapses. The **non-racy** alternative to a fixed
+ * `message` once `timeoutMs` elapses, or at once when the predicate throws, with
+ * the throw as the error's `cause`. The **non-racy** alternative to a fixed
  * sleep for awaiting an asynchronous side effect that lands on an observable
  * value.
  *
@@ -56,20 +62,62 @@ export interface WaitForOptions {
 export function waitFor(predicate: () => boolean, options: WaitForOptions = {}): Promise<void> {
    const timeoutMs = options.timeoutMs ?? 2000;
    const intervalMs = options.intervalMs ?? 5;
-   const message = options.message ?? `Timed out after ${timeoutMs}ms waiting for a condition`;
-   if (predicate()) {
-      return Promise.resolve();
-   }
+   const defaultMessage = `Timed out after ${timeoutMs}ms waiting for a condition`;
    return new Promise<void>((resolve, reject) => {
-      const deadline = setTimeout(() => {
+      // A throw from the predicate or the message function would leave the
+      // promise unsettled from the poll's or the deadline's timer, or escape
+      // `waitFor` itself on the first check; it rejects instead, with the
+      // predicate's throw, else the message function's, as cause. True once
+      // the promise is settled.
+      const settle = (timedOut: boolean): boolean => {
+         let met = false;
+         let threw = false;
+         let cause: unknown;
+         try {
+            met = predicate();
+         } catch (error: unknown) {
+            threw = true;
+            cause = error;
+         }
+         if (met) {
+            resolve();
+            return true;
+         }
+         if (!timedOut && !threw) {
+            return false;
+         }
+         let message = defaultMessage;
+         try {
+            if (typeof options.message === 'function') {
+               message = options.message();
+            } else if (options.message !== undefined) {
+               message = options.message;
+            }
+         } catch (error: unknown) {
+            if (!threw) {
+               threw = true;
+               cause = error;
+            }
+         }
+         reject(new Error(message, threw ? { cause } : undefined));
+         return true;
+      };
+      if (settle(false)) {
+         return;
+      }
+      const stop = (): void => {
          clearInterval(poll);
-         reject(new Error(message));
+         clearTimeout(deadline);
+      };
+      // A stalled loop can run the deadline after the condition came true but
+      // before the next poll saw it, so the deadline checks once more.
+      const deadline = setTimeout(() => {
+         settle(true);
+         stop();
       }, timeoutMs);
       const poll = setInterval(() => {
-         if (predicate()) {
-            clearInterval(poll);
-            clearTimeout(deadline);
-            resolve();
+         if (settle(false)) {
+            stop();
          }
       }, intervalMs);
    });

package/src/tracer.ts

@@ -12,6 +12,7 @@ import { Format, Logger, type LogThreshold } from './logger';
 import { NoopLogger } from './noop-logger';
 import { DefaultProfileSession, type ProfileSession } from './profile-session';
 import { Disposable } from './util';
+import { describeErrorWithStack } from './messages/primitives';
 
 /** Module-global so nested timers don't reuse ids. */
 let nextTimerId = 0;
@@ -181,15 +182,10 @@ export class DefaultTracer implements Tracer {
          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);
-            }
+            // Reporting the failure is the caller's, who receives it: a line at
+            // warn here would exist only while `logLevel` is enabled.
+            const detail = describeErrorWithStack(error);
+            this.logger.debug(`${label} [#${id}] failed: ${detail}`);
          }
       };
       let result: T;

package/src/transfer-document.ts

@@ -9,53 +9,123 @@
 
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
+import { asModelVersion, type ModelVersion, type TextVersion } from './model-service/base-version';
+
+/** The model a data server built for a document, encoded for the wire. */
+export interface TransferModelSnapshot<TRoot extends TransferElement, TDiagnostic = TransferDiagnostic> {
+   root: TRoot;
+   /** Absent until the document is validated; `[]` once it is and nothing was found. */
+   diagnostics?: TDiagnostic[];
+   /**
+    * The version of the text `root` was parsed from. A caller that mutates the
+    * model sends this back as the `baseVersion` of its write, and the server
+    * rejects the write with `ConflictError` once its text has moved past it.
+    */
+   version: ModelVersion;
+   /**
+    * The data server's fingerprint of `root` and `diagnostics`, or under its
+    * `'text-diagnostics'` strategy of the text `root` was parsed from and
+    * `diagnostics`.
+    * Independent of `version`; an equal hash also means equally validated.
+    */
+   hash: string;
+}
+
+/** The text a data server held for a document when it sent it. */
+export interface TextState {
+   /**
+    * The server's version of that text. A `TransferModelSnapshot.version` below it
+    * means the model was parsed from older text, and an update at this version
+    * or a later one follows.
+    */
+   version: TextVersion;
+   /**
+    * What `textHash` makes of the text alone: equal texts hash equal whatever
+    * their version or dirty state, across a revert or a server restart that
+    * numbers versions afresh.
+    */
+   hash: string;
+   /**
+    * Whether the text differs from the file, as the server last knew the file.
+    * A later change arrives as `onDocumentDirtyChanged` to a client watching
+    * the document.
+    */
+   dirty: boolean;
+}
 
 /**
  * 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.
+ * its clients: the server's model of a document and the text it holds for it,
+ * each absent where the server has none.
  *
  * 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}.
+ * see {@link TransferElement}).
  */
 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.
+    * 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.
     */
-   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[];
+   model?: TransferModelSnapshot<TTransfer, TDiagnostic>;
+   /** Absent when the server holds no text for the document. */
+   text?: TextState;
 }
 
 /**
- * A {@link TransferDocument} the server actually had, so `root` is present.
+ * A {@link TransferDocument} the server actually had, so `model` is present.
  * Narrowed to by {@link TransferDocument.isLoaded} / {@link TransferDocument.assertLoaded}.
  */
 export type LoadedTransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> = TransferDocument<
    TTransfer,
    TDiagnostic
 > & {
-   root: TTransfer;
+   model: TransferModelSnapshot<TTransfer, TDiagnostic>;
 };
 
+/**
+ * What a save or a persist answers: the document, and in `persisted` the
+ * version of the text it wrote to the file. That can differ from
+ * `model.version` either way, since writes land between the build and the
+ * take, so a client marking a version saved takes it from here.
+ */
+export type TransferSavedDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> = TransferDocument<
+   TTransfer,
+   TDiagnostic
+> & {
+   persisted: { version: TextVersion };
+};
+
+/**
+ * What a create answers: the document as a read after the create finds it,
+ * and in `created` the version the create's text took. Another client's write
+ * or an integrity repair can land between the create and that read, so
+ * `model.version` can be past it, and a write based on it would carry that
+ * text as the creator's; a write based on `created.version` conflicts instead.
+ * A model version, not a text version, because the creator holds the text at
+ * that version: it sent it.
+ */
+export type TransferCreatedDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> = TransferDocument<
+   TTransfer,
+   TDiagnostic
+> & {
+   created: { version: ModelVersion };
+};
+
+/** What a watch answers, once it is in place. */
+export interface TransferWatchedDocument {
+   /** The key the watch's events name the document by, which a symlinked URI does not spell. */
+   readonly uri: string;
+   /** Whether a document exists there; one the server fails to load counts, only a missing one does not. */
+   readonly exists: boolean;
+   /** The position of the last update or deletion event sent before `exists` was taken; an event past it was sent after. */
+   readonly sequence: number;
+   /** The text the server held when `exists` was taken, as a read answers it; absent when it held none. */
+   readonly text?: TextState;
+}
+
 export namespace TransferDocument {
    /**
     * Whether the server had this document. Branch on it where absence is an
@@ -64,13 +134,13 @@ export namespace TransferDocument {
    export function isLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
       document: TransferDocument<TTransfer, TDiagnostic>
    ): document is LoadedTransferDocument<TTransfer, TDiagnostic> {
-      return document.root !== undefined;
+      return document.model !== undefined;
    }
 
    /**
-    * The same document with `root` no longer optional, or a throw. For call
+    * The same document with `model` 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`
+    * returned because a caller needing `model` usually needs `uri` or `text`
     * with it.
     */
    export function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
@@ -82,18 +152,29 @@ export namespace TransferDocument {
       return document;
    }
 
+   /** The envelope for a document the server does not have. */
+   export function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      uri: string
+   ): TransferDocument<TTransfer, TDiagnostic> {
+      return { uri };
+   }
+
    /**
-    * 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.
+    * Construct a {@link TransferDocument} envelope with a model, its version
+    * marked as coming from a read. `diagnostics` absent means not validated.
     */
    export function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
       uri: string,
       version: number,
       root: TTransfer,
-      diagnostics: TDiagnostic[] = []
+      hash: string,
+      diagnostics?: TDiagnostic[],
+      text?: TextState
    ): TransferDocument<TTransfer, TDiagnostic> {
-      return { uri, version, root, diagnostics };
+      return {
+         uri,
+         model: { root, version: asModelVersion(version), hash, ...(diagnostics === undefined ? {} : { diagnostics }) },
+         ...(text === undefined ? {} : { text })
+      };
    }
 }

package/src/util.ts

@@ -146,12 +146,6 @@ export function asMutable<T>(item: T): Mutable<T> {
    return item;
 }
 
-/** Type-guard variant: narrows `item` to `Mutable<T> | undefined` if `guard` accepts it. */
-export function toMutable<T>(item: unknown, guard: TypeGuard<T>): item is Mutable<T> | undefined;
-export function toMutable<T>(item: unknown, guard?: TypeGuard<T>): item is Mutable<T> | undefined {
-   return guard ? guard(item) : true;
-}
-
 /**
  * Wrap `text` in `quoteChar`, escaping interior occurrences with `replaceChar`.
  *
@@ -248,3 +242,36 @@ export function getAt<T = unknown>(obj: unknown, path: string[]): T | undefined
    }
    return cur as T;
 }
+
+/**
+ * A stable, non-cryptographic digest of `text`, equal on every host for equal
+ * text: the `TextState.hash` a data server stamps, so a client can
+ * hash text of its own to compare. An array is read as its elements joined, so
+ * a large text is hashed in parts without concatenating it. It tells whether a
+ * text changed, not who could forge one.
+ */
+export function textHash(text: string | readonly string[]): string {
+   const { high, low } = cyrb53(typeof text === 'string' ? [text] : text);
+   return high.toString(16).padStart(8, '0') + low.toString(16).padStart(8, '0');
+}
+
+/**
+ * The two 32-bit words cyrb53 ends on, each unsigned, for `parts` read as one
+ * string. It needs no `node:*` module, so every host runs it.
+ */
+function cyrb53(parts: readonly string[]): { readonly high: number; readonly low: number } {
+   let h1 = 0xdeadbeef;
+   let h2 = 0x41c6ce57;
+   for (const part of parts) {
+      for (let i = 0; i < part.length; i++) {
+         const code = part.charCodeAt(i);
+         h1 = Math.imul(h1 ^ code, 2654435761);
+         h2 = Math.imul(h2 ^ code, 1597334677);
+      }
+   }
+   h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+   h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+   h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+   h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+   return { high: h2 >>> 0, low: h1 >>> 0 };
+}

package/lib/model-service/args.d.ts

@@ -1,64 +0,0 @@
-/********************************************************************************
- * 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
- ********************************************************************************/
-/**
- * Argument shapes for the in-process `ModelService` facade — the
- * canonical home for the lifecycle operation signatures. Implementation
- * lives in `@hydranium/core/langium/model-service`; this protocol
- * package owns the types so wire-side projections (the data-server
- * protocol in `./data`) can structurally extend them rather than
- * mirroring them by hand.
- *
- * `./model-server.ts` re-exports them, so an import from either path
- * resolves.
- */
-/** Identifies a client-document binding. Every facade operation carries these fields. */
-export interface TransferClientArgs {
-    /** Document URI. */
-    uri: string;
-    /** Stable identifier for the client invoking the operation. */
-    clientId: string;
-}
-/**
- * Update a document's content via the in-process facade. `model` may be
- * the structured (transfer-model or AST) root or its serialised textual
- * form — implementations decide which is faster on their transport.
- * Generic over `T` so adopters parameterise the structured shape against
- * their grammar's transfer-model overlay; passing a string is always
- * allowed.
- */
-export interface TransferUpdateArgs<T> extends TransferClientArgs {
-    /** Structured model root or its serialised textual form. */
-    model: T | string;
-    /**
-     * Optional based-on version: the text-document version this update
-     * was authored against. When set, the server compares against its
-     * current text-document version for `uri` and throws
-     * `ConflictError` on mismatch. Omit to opt out of the gate — mirrors
-     * LSP's `OptionalVersionedTextDocumentIdentifier` posture, intended
-     * for headless / CLI / batch tooling without a meaningful based-on
-     * version.
-     */
-    baseVersion?: number;
-}
-/**
- * Persist a document to disk via the in-process facade. Same `model`
- * shape as {@link TransferUpdateArgs}.
- */
-export interface TransferSaveArgs<T> extends TransferClientArgs {
-    /** Structured model root or its serialised textual form. */
-    model: T | string;
-    /**
-     * Optional based-on version — same semantics as
-     * {@link TransferUpdateArgs.baseVersion}. `save` delegates the gating
-     * check to its inner `update`, so this field threads through to the
-     * same `ConflictError` site.
-     */
-    baseVersion?: number;
-}
-//# sourceMappingURL=args.d.ts.map

package/lib/model-service/args.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/model-service/args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;GAUG;AAEH,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IAChC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC9D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC5D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/lib/model-service/args.js.map

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

package/src/model-service/args.ts

@@ -1,67 +0,0 @@
-/********************************************************************************
- * 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
- ********************************************************************************/
-
-/**
- * Argument shapes for the in-process `ModelService` facade — the
- * canonical home for the lifecycle operation signatures. Implementation
- * lives in `@hydranium/core/langium/model-service`; this protocol
- * package owns the types so wire-side projections (the data-server
- * protocol in `./data`) can structurally extend them rather than
- * mirroring them by hand.
- *
- * `./model-server.ts` re-exports them, so an import from either path
- * resolves.
- */
-
-/** Identifies a client-document binding. Every facade operation carries these fields. */
-export interface TransferClientArgs {
-   /** Document URI. */
-   uri: string;
-   /** Stable identifier for the client invoking the operation. */
-   clientId: string;
-}
-
-/**
- * Update a document's content via the in-process facade. `model` may be
- * the structured (transfer-model or AST) root or its serialised textual
- * form — implementations decide which is faster on their transport.
- * Generic over `T` so adopters parameterise the structured shape against
- * their grammar's transfer-model overlay; passing a string is always
- * allowed.
- */
-export interface TransferUpdateArgs<T> extends TransferClientArgs {
-   /** Structured model root or its serialised textual form. */
-   model: T | string;
-   /**
-    * Optional based-on version: the text-document version this update
-    * was authored against. When set, the server compares against its
-    * current text-document version for `uri` and throws
-    * `ConflictError` on mismatch. Omit to opt out of the gate — mirrors
-    * LSP's `OptionalVersionedTextDocumentIdentifier` posture, intended
-    * for headless / CLI / batch tooling without a meaningful based-on
-    * version.
-    */
-   baseVersion?: number;
-}
-
-/**
- * Persist a document to disk via the in-process facade. Same `model`
- * shape as {@link TransferUpdateArgs}.
- */
-export interface TransferSaveArgs<T> extends TransferClientArgs {
-   /** Structured model root or its serialised textual form. */
-   model: T | string;
-   /**
-    * Optional based-on version — same semantics as
-    * {@link TransferUpdateArgs.baseVersion}. `save` delegates the gating
-    * check to its inner `update`, so this field threads through to the
-    * same `ConflictError` site.
-    */
-   baseVersion?: number;
-}