@hydranium/protocol 1.0.0-next.10

package/lib/testing/wait-for.js

@@ -0,0 +1,67 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitFor = waitFor;
+exports.tick = tick;
+/**
+ * Resolve once `predicate()` returns true, polling at `intervalMs`; reject with
+ * `message` once `timeoutMs` elapses. The **non-racy** alternative to a fixed
+ * sleep for awaiting an asynchronous side effect that lands on an observable
+ * value.
+ *
+ * It resolves the instant the condition holds, so it is *faster* than a fixed
+ * delay on the happy path, and tolerates a slow event loop up to `timeoutMs`, so
+ * it does not flake under parallel CI where a fixed `setTimeout` can be starved
+ * past the test timeout.
+ *
+ * @example
+ * await proxy.updateModelDocument({ uri, clientId, model });
+ * await waitFor(() => harness.events.length === 1); // the notification crossed
+ * expect(harness.events[0].document.uri).toBe(uri);
+ */
+function waitFor(predicate, options = {}) {
+    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();
+    }
+    return new Promise((resolve, reject) => {
+        const deadline = setTimeout(() => {
+            clearInterval(poll);
+            reject(new Error(message));
+        }, timeoutMs);
+        const poll = setInterval(() => {
+            if (predicate()) {
+                clearInterval(poll);
+                clearTimeout(deadline);
+                resolve();
+            }
+        }, intervalMs);
+    });
+}
+/**
+ * Yield the event loop for `ms` (default 10). The bounded counterpart to
+ * {@link waitFor}, for the rare assertion that something has NOT happened — a
+ * *negative* you cannot poll positively. Give async delivery a real chance to
+ * (wrongly) occur, then assert it did not.
+ *
+ * A fixed yield is unavoidable here, but the failure mode is a false-green, not
+ * the flaky-red a fixed delay causes on a positive wait.
+ *
+ * @example
+ * await proxy.saveModelDocument({ uri, clientId, model }); // no subscriber yet
+ * await tick();                  // give a (wrongly) fired event a chance to land
+ * expect(savedEvents).toHaveLength(0); // assert the ABSENCE
+ */
+function tick(ms = 10) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=wait-for.js.map

package/lib/testing/wait-for.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for.js","sourceRoot":"","sources":["../../src/testing/wait-for.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAgDlF,0BAoBC;AAgBD,oBAEC;AAtDD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,OAAO,CAAC,SAAwB,EAAE,UAA0B,EAAE;IAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,mBAAmB,SAAS,4BAA4B,CAAC;IAC5F,IAAI,SAAS,EAAE,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,aAAa,CAAC,IAAI,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9B,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE;YAC3B,IAAI,SAAS,EAAE,EAAE,CAAC;gBACf,aAAa,CAAC,IAAI,CAAC,CAAC;gBACpB,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACvB,OAAO,EAAE,CAAC;YACb,CAAC;QACJ,CAAC,EAAE,UAAU,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,IAAI,CAAC,EAAE,GAAG,EAAE;IACzB,OAAO,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/lib/tracer.d.ts

@@ -0,0 +1,115 @@
+/********************************************************************************
+ * 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 } from './clock';
+import { Logger, type LogThreshold } from './logger';
+import { type ProfileSession } from './profile-session';
+import { Disposable } from './util';
+/** Ops completing before this threshold are silent on success — only failures emit a retroactive start. */
+export declare 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 declare class DefaultTracer implements Tracer {
+    protected readonly logger: Logger;
+    protected readonly clock: Clock;
+    protected readonly readMemory: MemoryReader;
+    constructor(logger?: Logger, clock?: Clock, readMemory?: MemoryReader);
+    error(message?: string, ...args: unknown[]): this;
+    warn(message?: string, ...args: unknown[]): this;
+    info(message?: string, ...args: unknown[]): this;
+    debug(message?: string, ...args: unknown[]): this;
+    trace(message?: string, ...args: unknown[]): this;
+    log(message?: string, ...args: unknown[]): this;
+    logAt(threshold: LogThreshold, message: string): this;
+    memory(label?: string, logLevel?: LogThreshold): void;
+    time<T>(label: string, callback: () => T, logLevel?: LogThreshold, options?: TimeOptions): T;
+    startTimer(label: string, logLevel?: LogThreshold, logAfterMs?: number): Disposable;
+    profile(identifier: string): ProfileSession;
+    for(component: string): this;
+    sub(component: string): this;
+    with(component: string): this;
+    withUri(uri: string): this;
+    /** Construct a sibling Tracer over a derived logger, preserving the concrete subclass. */
+    protected derive(logger: Logger): this;
+    /** Hook for appending status-bracket suffixes like memory deltas. Default: none. */
+    protected timingSuffix(_status: 'done' | 'failed' | 'cancelled', _elapsedMs: number, _options: TimeOptions): string;
+    /** Hook to differentiate cancelled operations from failures. Default: all errors are failures. */
+    protected categorizeError(_error: unknown): 'failed' | 'cancelled';
+}
+//# sourceMappingURL=tracer.d.ts.map

package/lib/tracer.d.ts.map

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

package/lib/tracer.js

@@ -0,0 +1,205 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultTracer = exports.DEFER_START_MS = void 0;
+const clock_1 = require("./clock");
+const logger_1 = require("./logger");
+const noop_logger_1 = require("./noop-logger");
+const profile_session_1 = require("./profile-session");
+const util_1 = require("./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. */
+exports.DEFER_START_MS = 5;
+/**
+ * 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.
+ */
+class DefaultTracer {
+    logger;
+    clock;
+    readMemory;
+    constructor(logger = new noop_logger_1.NoopLogger(), clock = new clock_1.SystemClock(), readMemory = () => undefined) {
+        this.logger = logger;
+        this.clock = clock;
+        this.readMemory = readMemory;
+    }
+    // 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, ...args) {
+        this.logger.error(message, ...args);
+        return this;
+    }
+    warn(message, ...args) {
+        this.logger.warn(message, ...args);
+        return this;
+    }
+    info(message, ...args) {
+        this.logger.info(message, ...args);
+        return this;
+    }
+    debug(message, ...args) {
+        this.logger.debug(message, ...args);
+        return this;
+    }
+    trace(message, ...args) {
+        this.logger.trace(message, ...args);
+        return this;
+    }
+    log(message, ...args) {
+        this.logger.log(message, ...args);
+        return this;
+    }
+    logAt(threshold, message) {
+        this.logger.logAt(threshold, message);
+        return this;
+    }
+    memory(label, logLevel = 'info') {
+        if (logLevel === 'off' || !logger_1.Logger.isLevelEnabled(logLevel)) {
+            return;
+        }
+        const info = this.readMemory();
+        if (!info) {
+            // No memory stats available — a contentless "Memory:" line is noise.
+            return;
+        }
+        const used = logger_1.Format.bytes(info.usedBytes);
+        const text = info.totalBytes !== undefined ? `${used}/${logger_1.Format.bytes(info.totalBytes)}` : used;
+        this.logger[logLevel](`${label ? `${label}: ` : 'Memory: '}${text}`);
+    }
+    time(label, callback, logLevel = 'info', options = {}) {
+        if (logLevel === 'off' || !logger_1.Logger.isLevelEnabled(logLevel)) {
+            return callback();
+        }
+        const { logAfterMs = exports.DEFER_START_MS, captureId, tags } = options;
+        const id = ++nextTimerId;
+        captureId?.(id);
+        const stopwatch = this.clock.stopwatch();
+        let startEmitted = false;
+        let startTimer;
+        const currentExtras = () => (tags && tags.length > 0 ? `, ${tags.join(', ')}` : '');
+        const emitStart = () => {
+            this.logger[logLevel](`${label} [#${id} start${currentExtras()}]`);
+            startEmitted = true;
+        };
+        if (logAfterMs <= 0) {
+            emitStart();
+        }
+        else {
+            startTimer = this.clock.setTimer(emitStart, logAfterMs);
+        }
+        const emit = (status, error) => {
+            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}, ${logger_1.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;
+        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;
+            });
+        }
+        emit('done');
+        return result;
+    }
+    startTimer(label, logLevel = 'info', logAfterMs = exports.DEFER_START_MS) {
+        if (logLevel === 'off' || !logger_1.Logger.isLevelEnabled(logLevel)) {
+            return util_1.Disposable.create(() => { });
+        }
+        const id = ++nextTimerId;
+        const stopwatch = this.clock.stopwatch();
+        let startEmitted = false;
+        let startTimer;
+        const emitStart = () => {
+            this.logger[logLevel](`${label} [#${id} start]`);
+            startEmitted = true;
+        };
+        if (logAfterMs <= 0) {
+            emitStart();
+        }
+        else {
+            startTimer = this.clock.setTimer(emitStart, logAfterMs);
+        }
+        return util_1.Disposable.create(() => {
+            startTimer?.dispose();
+            if (!startEmitted) {
+                return;
+            }
+            const elapsed = stopwatch.elapsedMs;
+            const suffix = this.timingSuffix('done', elapsed, {});
+            this.logger[logLevel](`${label} [#${id} done, ${logger_1.Format.elapsed(elapsed)}${suffix}]`);
+        });
+    }
+    profile(identifier) {
+        return new profile_session_1.DefaultProfileSession(this.logger, this.clock, identifier);
+    }
+    for(component) {
+        return this.derive(this.logger.for(component));
+    }
+    sub(component) {
+        return this.derive(this.logger.sub(component));
+    }
+    with(component) {
+        return this.derive(this.logger.with(component));
+    }
+    withUri(uri) {
+        return this.derive(this.logger.withUri(uri));
+    }
+    /** Construct a sibling Tracer over a derived logger, preserving the concrete subclass. */
+    derive(logger) {
+        return new DefaultTracer(logger, this.clock, this.readMemory);
+    }
+    /** Hook for appending status-bracket suffixes like memory deltas. Default: none. */
+    timingSuffix(_status, _elapsedMs, _options) {
+        return '';
+    }
+    /** Hook to differentiate cancelled operations from failures. Default: all errors are failures. */
+    categorizeError(_error) {
+        return 'failed';
+    }
+}
+exports.DefaultTracer = DefaultTracer;
+//# sourceMappingURL=tracer.js.map

package/lib/tracer.js.map

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

package/lib/transfer-diagnostic.d.ts

@@ -0,0 +1,73 @@
+/********************************************************************************
+ * 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 declare namespace TransferDiagnostic {
+    /** Path separator between AST nodes within an element location. */
+    const ELEMENT_SEGMENT_SEPARATOR = "/";
+    /** Index separator within an array property segment. */
+    const ELEMENT_INDEX_SEPARATOR = "@";
+    /** Property separator suffixing the element path with the offending property name. */
+    const ELEMENT_PROPERTY_SEPARATOR = "^";
+    function isError(diagnostic: TransferDiagnostic): boolean;
+    function isParseError(diagnostic: TransferDiagnostic): boolean;
+    function getPath(diagnostic: TransferDiagnostic): string;
+    function errors(diagnostics: TransferDiagnostic[]): TransferDiagnostic[];
+    function hasErrors(diagnostics: TransferDiagnostic[]): boolean;
+    function hasParseErrors(diagnostics: TransferDiagnostic[]): boolean;
+}
+//# sourceMappingURL=transfer-diagnostic.d.ts.map

package/lib/transfer-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-diagnostic.d.ts","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;IAC5D;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,yBAAiB,kBAAkB,CAAC;IACjC,mEAAmE;IAC5D,MAAM,yBAAyB,MAAM,CAAC;IAC7C,wDAAwD;IACjD,MAAM,uBAAuB,MAAM,CAAC;IAC3C,sFAAsF;IAC/E,MAAM,0BAA0B,MAAM,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAE/D;IAED,SAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAEpE;IAED,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAE9D;IAED,SAAgB,MAAM,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAE9E;IAED,SAAgB,SAAS,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEpE;IAED,SAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEzE;CACH"}

package/lib/transfer-diagnostic.js

@@ -0,0 +1,45 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransferDiagnostic = void 0;
+var TransferDiagnostic;
+(function (TransferDiagnostic) {
+    /** Path separator between AST nodes within an element location. */
+    TransferDiagnostic.ELEMENT_SEGMENT_SEPARATOR = '/';
+    /** Index separator within an array property segment. */
+    TransferDiagnostic.ELEMENT_INDEX_SEPARATOR = '@';
+    /** Property separator suffixing the element path with the offending property name. */
+    TransferDiagnostic.ELEMENT_PROPERTY_SEPARATOR = '^';
+    function isError(diagnostic) {
+        return diagnostic.severity === 'error';
+    }
+    TransferDiagnostic.isError = isError;
+    function isParseError(diagnostic) {
+        return diagnostic.type === 'parsing-error';
+    }
+    TransferDiagnostic.isParseError = isParseError;
+    function getPath(diagnostic) {
+        return diagnostic.property ? `${diagnostic.element}${TransferDiagnostic.ELEMENT_PROPERTY_SEPARATOR}${diagnostic.property}` : diagnostic.element;
+    }
+    TransferDiagnostic.getPath = getPath;
+    function errors(diagnostics) {
+        return diagnostics.filter(isError);
+    }
+    TransferDiagnostic.errors = errors;
+    function hasErrors(diagnostics) {
+        return diagnostics.some(isError);
+    }
+    TransferDiagnostic.hasErrors = hasErrors;
+    function hasParseErrors(diagnostics) {
+        return diagnostics.some(isParseError);
+    }
+    TransferDiagnostic.hasParseErrors = hasParseErrors;
+})(TransferDiagnostic || (exports.TransferDiagnostic = TransferDiagnostic = {}));
+//# sourceMappingURL=transfer-diagnostic.js.map

package/lib/transfer-diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-diagnostic.js","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAqDlF,IAAiB,kBAAkB,CA+BlC;AA/BD,WAAiB,kBAAkB;IAChC,mEAAmE;IACtD,4CAAyB,GAAG,GAAG,CAAC;IAC7C,wDAAwD;IAC3C,0CAAuB,GAAG,GAAG,CAAC;IAC3C,sFAAsF;IACzE,6CAA0B,GAAG,GAAG,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC1C,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,YAAY,CAAC,UAA8B;QACxD,OAAO,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;IAC9C,CAAC;IAFe,+BAAY,eAE3B,CAAA;IAED,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,mBAAA,0BAA0B,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;IAChI,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,MAAM,CAAC,WAAiC;QACrD,OAAO,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAFe,yBAAM,SAErB,CAAA;IAED,SAAgB,SAAS,CAAC,WAAiC;QACxD,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAFe,4BAAS,YAExB,CAAA;IAED,SAAgB,cAAc,CAAC,WAAiC;QAC7D,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAFe,iCAAc,iBAE7B,CAAA;AACJ,CAAC,EA/BgB,kBAAkB,kCAAlB,kBAAkB,QA+BlC"}

package/lib/transfer-document.d.ts

@@ -0,0 +1,73 @@
+/********************************************************************************
+ * 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 declare 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.
+     */
+    function isLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(document: TransferDocument<TTransfer, TDiagnostic>): document is LoadedTransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * 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.
+     */
+    function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(document: TransferDocument<TTransfer, TDiagnostic>): LoadedTransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * 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.
+     */
+    function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string, version: number, root: TTransfer, diagnostics?: TDiagnostic[]): TransferDocument<TTransfer, TDiagnostic>;
+}
+//# sourceMappingURL=transfer-document.d.ts.map

package/lib/transfer-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,IAAI,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;CACH"}