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

package/lib/index.d.ts

@@ -30,6 +30,7 @@ export * from './profiling';
 export * from './tracer';
 export * from './transfer-diagnostic';
 export * from './transfer-element';
+export * from './types';
 export * from './model-service';
 export * from './transfer-document';
 export * from './model-server';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AASlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AAIpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AASlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AAIpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC"}

package/lib/index.js

@@ -55,6 +55,7 @@ __exportStar(require("./profiling"), exports);
 __exportStar(require("./tracer"), exports);
 __exportStar(require("./transfer-diagnostic"), exports);
 __exportStar(require("./transfer-element"), exports);
+__exportStar(require("./types"), exports);
 __exportStar(require("./model-service"), exports);
 __exportStar(require("./transfer-document"), exports);
 __exportStar(require("./model-server"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iDAAiD;AAEjD,oDAAkC;AAClC,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,0CAAwB;AACxB,yCAAuB;AACvB,oDAAkC;AAClC,8CAA4B;AAC5B,4DAA0C;AAC1C,4DAA0C;AAC1C,2CAAyB;AACzB,qDAAmC;AACnC,2CAAyB;AACzB,sDAAoC;AACpC,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,oDAAkC;AAClC,8CAA4B;AAC5B,2CAAyB;AACzB,wDAAsC;AACtC,qDAAmC;AACnC,kDAAgC;AAChC,sDAAoC;AACpC,iDAA+B;AAC/B,4CAA0B;AAC1B,gDAA8B;AAC9B,uDAAqC;AACrC,wCAAsB;AACtB,wCAAsB;AACtB,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iDAAiD;AAEjD,oDAAkC;AAClC,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,0CAAwB;AACxB,yCAAuB;AACvB,oDAAkC;AAClC,8CAA4B;AAC5B,4DAA0C;AAC1C,4DAA0C;AAC1C,2CAAyB;AACzB,qDAAmC;AACnC,2CAAyB;AACzB,sDAAoC;AACpC,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,oDAAkC;AAClC,8CAA4B;AAC5B,2CAAyB;AACzB,wDAAsC;AACtC,qDAAmC;AACnC,0CAAwB;AACxB,kDAAgC;AAChC,sDAAoC;AACpC,iDAA+B;AAC/B,4CAA0B;AAC1B,gDAA8B;AAC9B,uDAAqC;AACrC,wCAAsB;AACtB,wCAAsB;AACtB,yCAAuB"}

package/lib/testing/index.d.ts

@@ -10,5 +10,6 @@ export * from './catalogue-audit';
 export * from './data-doubles';
 export * from './fake-clock';
 export * from './harness';
+export * from './transfer-node-builder';
 export * from './wait-for';
 //# sourceMappingURL=index.d.ts.map

package/lib/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAiBlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAiBlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}

package/lib/testing/index.js

@@ -26,8 +26,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
 // axis), `waitFor` / `tick`, the client-side data-head doubles
 // (`makeFakeDataPort` / `makeCapturingDataClient`), the translation-catalogue
-// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), and
-// the `Harness` marker
+// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), the
+// transfer-node builder (`makeTransferNodeBuilder`), and the `Harness` marker
 // interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
 // the test scaffolding in by default; adopters opt in by importing from
 // `@hydranium/protocol/testing`.
@@ -40,5 +40,6 @@ __exportStar(require("./catalogue-audit"), exports);
 __exportStar(require("./data-doubles"), exports);
 __exportStar(require("./fake-clock"), exports);
 __exportStar(require("./harness"), exports);
+__exportStar(require("./transfer-node-builder"), exports);
 __exportStar(require("./wait-for"), exports);
 //# sourceMappingURL=index.js.map

package/lib/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,8EAA8E;AAC9E,8EAA8E;AAC9E,uBAAuB;AACvB,0GAA0G;AAC1G,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAE/E,oDAAkC;AAClC,iDAA+B;AAC/B,+CAA6B;AAC7B,4CAA0B;AAC1B,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,0GAA0G;AAC1G,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAE/E,oDAAkC;AAClC,iDAA+B;AAC/B,+CAA6B;AAC7B,4CAA0B;AAC1B,0DAAwC;AACxC,6CAA2B"}

package/lib/testing/transfer-node-builder.d.ts

@@ -0,0 +1,81 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+import type { TransferElement } from '../transfer-element';
+import type { ConcreteTypeName, SingleTypeName } from '../types';
+/**
+ * The per-type constant the generated transfer model emits under each type's
+ * name, as Langium does for the AST. Its `$type` literal picks the interface
+ * out of the builder's type map.
+ */
+export interface TransferTypeConstant<TType extends string = string> {
+    readonly $type: TType;
+}
+/**
+ * What {@link makeTransferNodeBuilder} reads from a reflection: each type's
+ * grammar properties and their defaults. The generated
+ * `<LanguageId>TransferReflection` satisfies it without importing it, and
+ * keeps the literal type of its `types` so the builder can tell which fields
+ * the grammar defaults.
+ */
+export interface TransferReflection {
+    getTypeMetaData(type: string): {
+        readonly properties: Readonly<Record<string, {
+            readonly defaultValue?: unknown;
+        }>>;
+    };
+}
+/** The properties of `TType` that `TReflection`'s literal `types` gives a `defaultValue`; none for a reflection typed only as the interface. */
+type DefaultedKeys<TReflection, TType> = TReflection extends {
+    readonly types: infer Types;
+} ? TType extends keyof Types ? Types[TType] extends {
+    readonly properties: infer Properties;
+} ? {
+    [K in keyof Properties]: Properties[K] extends {
+        readonly defaultValue: unknown;
+    } ? K : never;
+}[keyof Properties] : never : never : never;
+/**
+ * Init payload of a {@link TransferNodeBuilder}: every field of `T` as its
+ * interface declares it, except that the fields named by `TDefaulted`, which
+ * the grammar defaults, are optional. `$type` comes from the constant.
+ */
+export type TransferNodeInit<T extends TransferElement, TDefaulted extends PropertyKey = never> = Omit<T, '$type' | TDefaulted> & Partial<Pick<T, Extract<TDefaulted, keyof T>>>;
+/**
+ * Transfer-node factory bound to a grammar's type map, the transfer twin of
+ * core's `AstNodeBuilder`. `TMap` is the generated `<LanguageId>TransferTypes`,
+ * `TReflection` the type of the generated reflection.
+ */
+export interface TransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection> {
+    /** A complete node: the grammar's defaults, then `init`. */
+    <TType extends ConcreteTypeName<TMap>>(typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>, init: TransferNodeInit<Extract<TMap[TType], TransferElement>, DefaultedKeys<TReflection, TType>>): Extract<TMap[TType], TransferElement>;
+    /**
+     * A node holding only `init`, with no defaults filled, typed as the
+     * incomplete node it is.
+     */
+    partial<TType extends ConcreteTypeName<TMap>>(typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>, init?: Partial<Omit<Extract<TMap[TType], TransferElement>, '$type'>>): Partial<Extract<TMap[TType], TransferElement>> & TransferTypeConstant<TType>;
+}
+/**
+ * Bind a {@link TransferNodeBuilder} to a grammar's reflection, so a test names
+ * only the fields it cares about and a containment field the grammar gains
+ * later needs no change at the call site.
+ *
+ * Defaults come from the reflection's grammar metadata alone, so a derived
+ * field the overlay adds is never defaulted, and stays required. An array
+ * default is a fresh `[]` per node. An init field named as `undefined` keeps
+ * its default, since the init type cannot refuse `undefined` for an optional
+ * field and a plain assign would leave the node typed complete without it.
+ *
+ * The constant's `$type` is written after `init`, because the init type keeps
+ * out only a `$type` written in the call: a spread of another node passes the
+ * check and would otherwise hand back a node typed as one type and tagged as
+ * another.
+ */
+export declare function makeTransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection>(reflection: TReflection): TransferNodeBuilder<TMap, TReflection>;
+export {};
+//# sourceMappingURL=transfer-node-builder.d.ts.map

package/lib/testing/transfer-node-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-node-builder.d.ts","sourceRoot":"","sources":["../../src/testing/transfer-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAChE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAChC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC,CAAA;KAAE,CAAC;CACxH;AAED,gJAAgJ;AAChJ,KAAK,aAAa,CAAC,WAAW,EAAE,KAAK,IAAI,WAAW,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,GACvF,KAAK,SAAS,MAAM,KAAK,GACtB,KAAK,CAAC,KAAK,CAAC,SAAS;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,UAAU,CAAA;CAAE,GAC3D;KAAG,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;KAAE,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,UAAU,CAAC,GACnH,KAAK,GACR,KAAK,GACR,KAAK,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,EAAE,UAAU,SAAS,WAAW,GAAG,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,GAC5H,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IACnG,4DAA4D;IAC5D,CAAC,KAAK,SAAS,gBAAgB,CAAC,IAAI,CAAC,EAClC,YAAY,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,EACjE,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,GAChG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,KAAK,SAAS,gBAAgB,CAAC,IAAI,CAAC,EACzC,YAAY,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,EACjE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC,GACpE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;CAClF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EACtG,UAAU,EAAE,WAAW,GACvB,mBAAmB,CAAC,IAAI,EAAE,WAAW,CAAC,CAkBxC"}

package/lib/testing/transfer-node-builder.js

@@ -0,0 +1,47 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTransferNodeBuilder = makeTransferNodeBuilder;
+/**
+ * Bind a {@link TransferNodeBuilder} to a grammar's reflection, so a test names
+ * only the fields it cares about and a containment field the grammar gains
+ * later needs no change at the call site.
+ *
+ * Defaults come from the reflection's grammar metadata alone, so a derived
+ * field the overlay adds is never defaulted, and stays required. An array
+ * default is a fresh `[]` per node. An init field named as `undefined` keeps
+ * its default, since the init type cannot refuse `undefined` for an optional
+ * field and a plain assign would leave the node typed complete without it.
+ *
+ * The constant's `$type` is written after `init`, because the init type keeps
+ * out only a `$type` written in the call: a spread of another node passes the
+ * check and would otherwise hand back a node typed as one type and tagged as
+ * another.
+ */
+function makeTransferNodeBuilder(reflection) {
+    const build = (typeConstant, init) => {
+        const node = { $type: typeConstant.$type };
+        for (const [name, property] of Object.entries(reflection.getTypeMetaData(typeConstant.$type).properties)) {
+            if (property.defaultValue !== undefined) {
+                node[name] = Array.isArray(property.defaultValue) ? [...property.defaultValue] : property.defaultValue;
+            }
+        }
+        for (const [name, value] of Object.entries(init)) {
+            if (value !== undefined || !Object.hasOwn(node, name)) {
+                node[name] = value;
+            }
+        }
+        node.$type = typeConstant.$type;
+        return node;
+    };
+    const partial = (typeConstant, init = {}) => ({ ...init, $type: typeConstant.$type });
+    return Object.assign(build, { partial });
+}
+//# sourceMappingURL=transfer-node-builder.js.map

package/lib/testing/transfer-node-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-node-builder.js","sourceRoot":"","sources":["../../src/testing/transfer-node-builder.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AA+DlF;;;;;;;;;;;;;;;GAeG;AACH,iCACG,UAAuB;IAEvB,MAAM,KAAK,GAAG,CAAC,YAAkC,EAAE,IAAY,EAAU,EAAE;QACxE,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;QACpE,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;YACxG,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBACvC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC1G,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBACrD,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC;QAChC,OAAO,IAAI,CAAC;IACf,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,YAAkC,EAAE,IAAI,GAAW,EAAE,EAAU,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5H,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,CAA2C,CAAC;AACtF,CAAC"}

package/lib/transfer-element.d.ts

@@ -26,10 +26,10 @@ export interface TransferElement {
  * declared wire shape — or fall back to the structural base
  * {@link TransferElement} when no entry is declared.
  *
- * Adopters declare the overlay by interface merging or by generating an
- * interface keyed on those `$type` strings. Types not in the overlay resolve to
- * `TransferElement` — the framework default behaves correctly without an
- * overlay (no autocomplete, but no compile error either).
+ * The transfer-model generator emits the overlay as `<LanguageId>TransferTypes`;
+ * an encoder that relabels a type overrides that entry. Types not in the
+ * overlay resolve to `TransferElement` — the framework default behaves
+ * correctly without an overlay (no autocomplete, but no compile error either).
  *
  * The lookup is compile-time only; no runtime cost.
  */

package/lib/types.d.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * The keys of a type map, Langium's `<LanguageName>AstType` or the generated
+ * `<LanguageId>TransferTypes`, that a node can carry as its `$type`: those
+ * listed in their own type's `$type`. A union, or an abstract type whose
+ * `$type` names only its subtypes, has a constant too, but building one would
+ * yield a node that no guard accepts. A concrete type with subtypes lists its
+ * own name beside theirs, as Langium writes it, and stays buildable.
+ */
+export type ConcreteTypeName<TMap> = {
+    [K in keyof TMap]: K extends (TMap[K] extends {
+        readonly $type: infer TType;
+    } ? TType : never) ? K : never;
+}[keyof TMap] & string;
+type IsUnion<T, TAll = T> = T extends unknown ? ([TAll] extends [T] ? false : true) : never;
+/**
+ * Intersected onto a builder's type-constant parameter, refuses a constant
+ * typed by a union of type names: the init would hold only the members' common
+ * fields, so either type could be built incomplete.
+ */
+export type SingleTypeName<TType> = true extends IsUnion<TType> ? {
+    readonly $type: never;
+} : unknown;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,IAAI;KACjC,CAAC,IAAI,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,KAAK,CAAA;KAAE,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK;CAC5G,CAAC,MAAM,IAAI,CAAC,GACV,MAAM,CAAC;AAEV,KAAK,OAAO,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,IAAI,SAAS,OAAO,CAAC,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC"}

package/lib/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.315",
+  "version": "1.0.0-next.317",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",

package/src/index.ts

@@ -41,6 +41,7 @@ export * from './profiling';
 export * from './tracer';
 export * from './transfer-diagnostic';
 export * from './transfer-element';
+export * from './types';
 export * from './model-service';
 export * from './transfer-document';
 export * from './model-server';

package/src/testing/index.ts

@@ -11,8 +11,8 @@
 // primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
 // axis), `waitFor` / `tick`, the client-side data-head doubles
 // (`makeFakeDataPort` / `makeCapturingDataClient`), the translation-catalogue
-// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), and
-// the `Harness` marker
+// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), the
+// transfer-node builder (`makeTransferNodeBuilder`), and the `Harness` marker
 // interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
 // the test scaffolding in by default; adopters opt in by importing from
 // `@hydranium/protocol/testing`.
@@ -26,4 +26,5 @@ export * from './catalogue-audit';
 export * from './data-doubles';
 export * from './fake-clock';
 export * from './harness';
+export * from './transfer-node-builder';
 export * from './wait-for';

package/src/testing/transfer-node-builder.ts

@@ -0,0 +1,107 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+import type { TransferElement } from '../transfer-element';
+import type { ConcreteTypeName, SingleTypeName } from '../types';
+
+/**
+ * The per-type constant the generated transfer model emits under each type's
+ * name, as Langium does for the AST. Its `$type` literal picks the interface
+ * out of the builder's type map.
+ */
+export interface TransferTypeConstant<TType extends string = string> {
+   readonly $type: TType;
+}
+
+/**
+ * What {@link makeTransferNodeBuilder} reads from a reflection: each type's
+ * grammar properties and their defaults. The generated
+ * `<LanguageId>TransferReflection` satisfies it without importing it, and
+ * keeps the literal type of its `types` so the builder can tell which fields
+ * the grammar defaults.
+ */
+export interface TransferReflection {
+   getTypeMetaData(type: string): { readonly properties: Readonly<Record<string, { readonly defaultValue?: unknown }>> };
+}
+
+/** The properties of `TType` that `TReflection`'s literal `types` gives a `defaultValue`; none for a reflection typed only as the interface. */
+type DefaultedKeys<TReflection, TType> = TReflection extends { readonly types: infer Types }
+   ? TType extends keyof Types
+      ? Types[TType] extends { readonly properties: infer Properties }
+         ? { [K in keyof Properties]: Properties[K] extends { readonly defaultValue: unknown } ? K : never }[keyof Properties]
+         : never
+      : never
+   : never;
+
+/**
+ * Init payload of a {@link TransferNodeBuilder}: every field of `T` as its
+ * interface declares it, except that the fields named by `TDefaulted`, which
+ * the grammar defaults, are optional. `$type` comes from the constant.
+ */
+export type TransferNodeInit<T extends TransferElement, TDefaulted extends PropertyKey = never> = Omit<T, '$type' | TDefaulted> &
+   Partial<Pick<T, Extract<TDefaulted, keyof T>>>;
+
+/**
+ * Transfer-node factory bound to a grammar's type map, the transfer twin of
+ * core's `AstNodeBuilder`. `TMap` is the generated `<LanguageId>TransferTypes`,
+ * `TReflection` the type of the generated reflection.
+ */
+export interface TransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection> {
+   /** A complete node: the grammar's defaults, then `init`. */
+   <TType extends ConcreteTypeName<TMap>>(
+      typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>,
+      init: TransferNodeInit<Extract<TMap[TType], TransferElement>, DefaultedKeys<TReflection, TType>>
+   ): Extract<TMap[TType], TransferElement>;
+   /**
+    * A node holding only `init`, with no defaults filled, typed as the
+    * incomplete node it is.
+    */
+   partial<TType extends ConcreteTypeName<TMap>>(
+      typeConstant: TransferTypeConstant<TType> & SingleTypeName<TType>,
+      init?: Partial<Omit<Extract<TMap[TType], TransferElement>, '$type'>>
+   ): Partial<Extract<TMap[TType], TransferElement>> & TransferTypeConstant<TType>;
+}
+
+/**
+ * Bind a {@link TransferNodeBuilder} to a grammar's reflection, so a test names
+ * only the fields it cares about and a containment field the grammar gains
+ * later needs no change at the call site.
+ *
+ * Defaults come from the reflection's grammar metadata alone, so a derived
+ * field the overlay adds is never defaulted, and stays required. An array
+ * default is a fresh `[]` per node. An init field named as `undefined` keeps
+ * its default, since the init type cannot refuse `undefined` for an optional
+ * field and a plain assign would leave the node typed complete without it.
+ *
+ * The constant's `$type` is written after `init`, because the init type keeps
+ * out only a `$type` written in the call: a spread of another node passes the
+ * check and would otherwise hand back a node typed as one type and tagged as
+ * another.
+ */
+export function makeTransferNodeBuilder<TMap, TReflection extends TransferReflection = TransferReflection>(
+   reflection: TReflection
+): TransferNodeBuilder<TMap, TReflection> {
+   const build = (typeConstant: TransferTypeConstant, init: object): object => {
+      const node: Record<string, unknown> = { $type: typeConstant.$type };
+      for (const [name, property] of Object.entries(reflection.getTypeMetaData(typeConstant.$type).properties)) {
+         if (property.defaultValue !== undefined) {
+            node[name] = Array.isArray(property.defaultValue) ? [...property.defaultValue] : property.defaultValue;
+         }
+      }
+      for (const [name, value] of Object.entries(init)) {
+         if (value !== undefined || !Object.hasOwn(node, name)) {
+            node[name] = value;
+         }
+      }
+      node.$type = typeConstant.$type;
+      return node;
+   };
+   const partial = (typeConstant: TransferTypeConstant, init: object = {}): object => ({ ...init, $type: typeConstant.$type });
+   return Object.assign(build, { partial }) as TransferNodeBuilder<TMap, TReflection>;
+}

package/src/transfer-element.ts

@@ -29,10 +29,10 @@ export interface TransferElement {
  * declared wire shape — or fall back to the structural base
  * {@link TransferElement} when no entry is declared.
  *
- * Adopters declare the overlay by interface merging or by generating an
- * interface keyed on those `$type` strings. Types not in the overlay resolve to
- * `TransferElement` — the framework default behaves correctly without an
- * overlay (no autocomplete, but no compile error either).
+ * The transfer-model generator emits the overlay as `<LanguageId>TransferTypes`;
+ * an encoder that relabels a type overrides that entry. Types not in the
+ * overlay resolve to `TransferElement` — the framework default behaves
+ * correctly without an overlay (no autocomplete, but no compile error either).
  *
  * The lookup is compile-time only; no runtime cost.
  */

package/src/types.ts

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The keys of a type map, Langium's `<LanguageName>AstType` or the generated
+ * `<LanguageId>TransferTypes`, that a node can carry as its `$type`: those
+ * listed in their own type's `$type`. A union, or an abstract type whose
+ * `$type` names only its subtypes, has a constant too, but building one would
+ * yield a node that no guard accepts. A concrete type with subtypes lists its
+ * own name beside theirs, as Langium writes it, and stays buildable.
+ */
+export type ConcreteTypeName<TMap> = {
+   [K in keyof TMap]: K extends (TMap[K] extends { readonly $type: infer TType } ? TType : never) ? K : never;
+}[keyof TMap] &
+   string;
+
+type IsUnion<T, TAll = T> = T extends unknown ? ([TAll] extends [T] ? false : true) : never;
+
+/**
+ * Intersected onto a builder's type-constant parameter, refuses a constant
+ * typed by a union of type names: the init would hold only the members' common
+ * fields, so either type could be built incomplete.
+ */
+export type SingleTypeName<TType> = true extends IsUnion<TType> ? { readonly $type: never } : unknown;