@hydranium/protocol 1.0.0-next.12 → 1.0.0-next.123

package/src/transfer-diagnostic.ts

@@ -7,6 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type MessageParams, type ResolvedMessage } from './messages/primitives';
+
 /**
  * Generic, transport-friendly diagnostic shape used by the model-server protocol.
  *
@@ -56,6 +58,21 @@ export interface TransferDiagnostic {
     * is not usable as a rule identity on its own.
     */
    code?: number | string;
+   /**
+    * Substitutions for the placeholders in the message this {@link code} names,
+    * present only for a diagnostic raised from a framework message declaration.
+    *
+    * Without them a translated template renders with its `{name}` tokens left
+    * standing, because substitution leaves an unmatched token in place rather
+    * than raising — so a surface that translates from {@link code} alone is
+    * correct for a parameterless sentence and visibly wrong for a parameterised
+    * one. This is the field that makes the second case work; the LSP carrier has
+    * always moved the params, and no carrier below it did.
+    *
+    * Prefer {@link TransferDiagnostic.resolved} over reading this: it decides
+    * whether an identity is present at all, which a lone `params` cannot.
+    */
+   params?: MessageParams;
 }
 
 export namespace TransferDiagnostic {
@@ -74,6 +91,29 @@ export namespace TransferDiagnostic {
       return diagnostic.type === 'parsing-error';
    }
 
+   /**
+    * The diagnostic as a renderable message, for a surface that translates.
+    * `undefined` when it carries no framework identity — a syntactic error, an
+    * adopter's own check, a linker failure — which is the case a caller must
+    * distinguish rather than render.
+    *
+    * Hand the result to `renderFrameworkMessage` with whatever catalogue the
+    * host has loaded. The `text` is the server's English, so a code the
+    * catalogue does not carry still yields a complete sentence.
+    *
+    * `code` alone does not establish an identity: it also holds Langium's
+    * internal code and an adopter's own, and either would be looked up against a
+    * catalogue that cannot have it. Requiring `params` is what discriminates,
+    * and it is why a parameterless framework message still populates the field
+    * with an empty object rather than omitting it.
+    */
+   export function resolved(diagnostic: TransferDiagnostic): ResolvedMessage | undefined {
+      if (typeof diagnostic.code !== 'string' || diagnostic.params === undefined) {
+         return undefined;
+      }
+      return { code: diagnostic.code, params: diagnostic.params, text: diagnostic.message };
+   }
+
    export function getPath(diagnostic: TransferDiagnostic): string {
       return diagnostic.property ? `${diagnostic.element}${ELEMENT_PROPERTY_SEPARATOR}${diagnostic.property}` : diagnostic.element;
    }

package/src/transfer-document.ts

@@ -9,6 +9,7 @@
 
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
+import { asSnapshotVersion, type SnapshotVersion } from './model-service/based-on';
 
 /**
  * Wire envelope exchanged between the model-server's data-server head and
@@ -27,14 +28,13 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
    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`.
+    * server's text-document version counter. A caller that mutates the document
+    * subsequently sends this straight back as `TransferUpdateDocumentArgs.basedOn`, and
+    * the server rejects a stale-based update with `ConflictError`.
     *
     * See `@hydranium/protocol#errors` for the conflict-detection contract.
     */
-   version: number;
+   version: SnapshotVersion;
    /**
     * 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
@@ -82,6 +82,21 @@ export namespace TransferDocument {
       return document;
    }
 
+   /**
+    * The envelope for a document the server does not have — `root` absent, and
+    * the version a read of a URI the store never saw reports.
+    *
+    * Exists so the absent branch is built the same way the present one is: both
+    * doors mark the version as coming from a read, and neither asks a caller to
+    * do it.
+    */
+   export function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      uri: string,
+      diagnostics: TDiagnostic[] = []
+   ): TransferDocument<TTransfer, TDiagnostic> {
+      return { uri, version: asSnapshotVersion(0), root: undefined, diagnostics };
+   }
+
    /**
     * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
     * to `[]` so test fixtures, fake protocol implementations, and the
@@ -94,6 +109,6 @@ export namespace TransferDocument {
       root: TTransfer,
       diagnostics: TDiagnostic[] = []
    ): TransferDocument<TTransfer, TDiagnostic> {
-      return { uri, version, root, diagnostics };
+      return { uri, version: asSnapshotVersion(version), root, diagnostics };
    }
 }

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

@@ -1,11 +0,0 @@
-"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 });
-//# sourceMappingURL=args.js.map

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;
-}