@hydranium/cli 1.0.0-next.27 → 1.0.0-next.270

package/package.json

@@ -1,34 +1,46 @@
 {
   "name": "@hydranium/cli",
-  "version": "1.0.0-next.27",
+  "version": "1.0.0-next.270",
   "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
   "keywords": [
+    "cli",
+    "codegen",
     "hydranium",
     "langium",
     "language-server",
-    "lsp",
-    "cli",
-    "codegen"
+    "lsp"
   ],
   "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/cli",
   "bugs": {
     "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
   },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/eclipse-emfcloud/hydranium.git",
     "directory": "packages/cli"
   },
-  "license": "MIT",
-  "author": {
-    "name": "Hydranium Team"
+  "bin": {
+    "hydranium-cli": "bin/hydranium-cli.js"
   },
+  "files": [
+    "bin",
+    "lib",
+    "src",
+    "heap-analysis",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "type": "module",
   "sideEffects": [
     "./lib/cli.js",
     "./lib/commands/*-driver.js",
     "./lib/testing/echo-server.js"
   ],
-  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -39,21 +51,13 @@
       "default": "./lib/cli.js"
     }
   },
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "bin": {
-    "hydranium-cli": "lib/cli.js"
+  "publishConfig": {
+    "access": "public"
   },
-  "files": [
-    "lib",
-    "src",
-    "heap-analysis",
-    "!lib/**/*.tsbuildinfo"
-  ],
   "scripts": {
-    "build": "tsc -b && node -e \"require('node:fs').chmodSync('lib/cli.js',0o755)\"",
+    "build": "tsc -b",
     "clean": "rimraf lib tsconfig.tsbuildinfo",
-    "lint": "eslint src test --max-warnings 0",
+    "lint": "oxlint --format stylish --config ../../oxlint.config.cjs src test --max-warnings 0",
     "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
     "test": "npm run typecheck:test && vitest run",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
@@ -65,23 +69,33 @@
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.27",
-    "@hydranium/data-server": "1.0.0-next.27",
-    "@hydranium/langium": "1.0.0-next.27",
-    "@hydranium/protocol": "1.0.0-next.27",
+    "@eclipse-glsp/graph": "2.7.0",
+    "@eclipse-glsp/server": "2.7.0",
+    "@hydranium/core": "1.0.0-next.270",
+    "@hydranium/data-server": "1.0.0-next.270",
+    "@hydranium/glsp-server": "1.0.0-next.270",
+    "@hydranium/langium": "1.0.0-next.270",
+    "@hydranium/protocol": "1.0.0-next.270",
+    "@types/node": "^22.0.0",
+    "inversify": "6.2.2",
+    "langium": "4.3.1",
+    "langium-cli": "4.3.0",
+    "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
-    "vscode-jsonrpc": "9.0.1",
-    "vscode-languageserver": "~10.0.1"
+    "typescript": "^7.0.2",
+    "vitest": "^4.0.0",
+    "vscode-jsonrpc": "9.0.0",
+    "vscode-languageserver": "10.0.1",
+    "vscode-languageserver-protocol": "3.18.1"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.27",
-    "@hydranium/data-server": "1.0.0-next.27",
-    "@hydranium/langium": "1.0.0-next.27",
-    "@hydranium/protocol": "1.0.0-next.27",
+    "@hydranium/core": "1.0.0-next.270",
+    "@hydranium/data-server": "1.0.0-next.270",
+    "@hydranium/langium": "1.0.0-next.270",
+    "@hydranium/protocol": "1.0.0-next.270",
     "@memlab/core": "^2.0.3",
     "@memlab/heap-analysis": "^2.0.3",
-    "vscode-jsonrpc": "9.0.1"
+    "vscode-jsonrpc": "^9.0.0"
   },
   "peerDependenciesMeta": {
     "@memlab/core": {
@@ -94,13 +108,10 @@
   "engines": {
     "node": ">=22.13"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "//build": "The chmod is load-bearing, not cruft. npm sets a bin's executable bit through bin-links' fixBin, but ONLY when it first creates the link — and `tsc` never sets it, so after `npm run clean` (which deletes lib/) a rebuild leaves lib/cli.js at 0644 and the node_modules/.bin/hydranium-cli symlink resolves to a non-executable target. Every example's `generate` step then dies with `sh: hydranium-cli: Permission denied`, surfacing as an opaque npm error code 127 during `turbo run build`. npm rebuild, npm rebuild @hydranium/cli AND a full npm install all fail to restore it, because npm will not revisit an existing workspace symlink; only a from-scratch `rm -rf node_modules` install does. Written as `node -e` rather than `chmod +x` so it stays portable — on Windows npm generates .cmd/.ps1 shims where the bit is irrelevant and chmodSync is harmless. The example packages' bins need no such step: their tests spawn them via process.execPath, never through the shim.",
-  "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. It is declared in the `/lib/` spelling ONLY: that spelling already resolves under both of this repo's module resolvers, so the twin rule (which exists so a BARE subpath is reachable from node10) has nothing to add here and a bare twin would only be a second name for one artefact. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
+  "//devDependencies": "Every package an `init` scaffold declares, other than this one, is declared here, whether or not `src` uses it: the scaffold-compiles test compiles and runs scaffolds inside this package, so their imports and tools resolve through these declarations. `check:init-provenance` holds this list and its versions to the scaffold's manifest.",
+  "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
   "//memlab": "@memlab/core and @memlab/heap-analysis are OPTIONAL PEER dependencies, not optionalDependencies, and the distinction is the whole point: npm installs optionalDependencies BY DEFAULT, both memlab packages pin puppeteer exactly, and puppeteer's postinstall downloads a Chrome binary — so every adopter of this CLI paid ~86 MB and a browser download for the one subcommand almost none of them run, and the download can fail and be walked past as a warning. An optional peer is not auto-installed, so `analyze-heap` documents `npm install @memlab/core @memlab/heap-analysis` as the opt-in and every other subcommand is unaffected. Taken pre-publish deliberately: after publish the install shape is what adopters already have.",
-  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest.",
-  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//peerDependencies": "`vscode-jsonrpc` takes a caret, so the framework shares the transport the LSP connection resolves, which an `init` scaffold pins: each `vscode-languageserver-protocol` release pins its transport exactly, so an exact peer would name a copy a fresh install rarely holds. The caret excludes 8.x, so a tree whose top holds GLSP's copy fails the peer with a named ERESOLVE warning, an error under `--strict-peer-deps`, rather than resolving silently. No peer reaches a NESTED copy, such as GLSP's or one the LSP packages nest. The wire compares message types and `ResponseError`s by copy identity, so the framework sends typed messages by method name and recognises errors with `isResponseError` rather than `instanceof`.",
+  "//prepack": "The publish guard, a `prepack` rather than a `prepare`: `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "The listed modules RUN on load rather than exporting anything: `cli.js` is the `bin`, each `*-driver.js` is spawned as its own process and calls `main(process.argv)` at top level, and `echo-server.js` starts a server. Their whole purpose is the effect, so a bundler must never treat them as prunable. Everything else here is library code with no module-level state beyond `new URL(..., import.meta.url)` constants."
 }

package/src/cli.ts

@@ -9,6 +9,7 @@
  ********************************************************************************/
 
 import { Command } from 'commander';
+import { describeError } from '@hydranium/protocol';
 import { readCliVersion } from './cli-version.js';
 import { runAnalyzeHeapCommand } from './commands/analyze-heap-args.js';
 import { runAstGroundTruthCommand } from './commands/ast-ground-truth-args.js';
@@ -134,6 +135,6 @@ main(process.argv.slice(2)).catch(err => {
    if (err instanceof InitWizardCancelled) {
       process.exit(130);
    }
-   console.error(err instanceof Error ? err.message : String(err));
+   console.error(describeError(err));
    process.exit(1);
 });

package/src/commands/analyze-heap.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { fileURLToPath } from 'node:url';
+import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
 import { spawnNodeChild } from './headless-harness.js';
 
 /**
@@ -41,6 +42,8 @@ export interface AnalyzeHeapDeps {
    readonly __spawnForTest?: (execArgs: string[]) => Promise<number>;
    /** Override the memlab-availability check. */
    readonly __memlabInstalledForTest?: () => boolean;
+   /** Decide the heap ceiling from a stated cgroup reading rather than the machine's. */
+   readonly __heapReadingForTest?: HeapReading;
 }
 
 /**
@@ -69,7 +72,7 @@ export async function runAnalyzeHeap(args: string[], deps: AnalyzeHeapDeps = {})
       return;
    }
    const spawnChild = deps.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(['--max-old-space-size=8192', ANALYZER, ...args]);
+   const code = await spawnChild([...driverHeapArgs(deps.__heapReadingForTest), ANALYZER, ...args]);
    if (code) {
       process.exitCode = code;
    }

package/src/commands/ast-ground-truth-args.ts

@@ -10,32 +10,34 @@
 import { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 
 /**
  * Every flag `ast-ground-truth` accepts, derived from the sets the parser is
- * handed so the list cannot claim a flag the parser would reject. `--services`
- * is consumed by the shared harness parser itself, so it is in neither set.
+ * handed so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const AST_GROUND_TRUTH_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const AST_GROUND_TRUTH_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
 export const AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[] = AST_GROUND_TRUTH_FLAGS;
 
 /** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
 export const AST_GROUND_TRUTH_HELP: readonly string[] = [
-   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli ast-ground-truth --services <module> [--import <specifier>]... <workspace> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Tally a workspace's live-model AST nodes by `$type` — the ground truth that",
    '`analyze-heap --validate <gt.json>` checks a heap snapshot against. `<module>`',
@@ -44,14 +46,15 @@ export const AST_GROUND_TRUTH_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --out-file <file>     Write the JSON to this file instead of stdout.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseAstGroundTruthArgs(args: string[], onError: UsageError = exitWithUsage): AstGroundTruthCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
-   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
+   return { servicesModule, imports, workspace, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runAstGroundTruthCommand(args: string[]): Promise<void> {

package/src/commands/ast-ground-truth-driver.ts

@@ -16,6 +16,7 @@
  */
 
 import * as fs from 'node:fs';
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 
 interface DriverArgs {
@@ -76,6 +77,6 @@ async function main(argv: string[]): Promise<void> {
 main(process.argv.slice(2))
    .then(() => process.exit(0))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/ast-ground-truth.ts

@@ -45,5 +45,5 @@ export function buildGroundTruthDriverArgs(options: AstGroundTruthCommandOptions
  * `--out-file`). No `--expose-gc` needed — this walks the AST, it does not weigh it.
  */
 export function runAstGroundTruth(options: AstGroundTruthCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildGroundTruthDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildGroundTruthDriverArgs(options)], options);
 }

package/src/commands/generate-ast-builder.ts

@@ -0,0 +1,246 @@
+/********************************************************************************
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import type { SourceFile } from 'ts-morph';
+
+/** Inputs for {@link emitAstBuilder}, resolved by the transfer-model command. */
+export interface EmitAstBuilderOptions {
+   /** Destination path for the generated builder module. */
+   outFile: string;
+   /** Path to the Langium-generated AST file the builder imports from. */
+   astFile: string;
+   /** Language id derived from the `<LanguageId>AstReflection` class name. */
+   languageId: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+/**
+ * A single `makeAstNodeBuilder` binding the generator emits.
+ *
+ * `typeMap` is the type expression handed to the generic — the whole-project
+ * alias for the merged binding, `<Namespace>.AstType` for a narrowed one.
+ */
+interface BuilderBinding {
+   exportName: string;
+   typeMap: string;
+   /** Grammar this binding is narrowed to; absent on the merged binding. */
+   namespace?: string;
+}
+
+/**
+ * Langium declares this type alias inside each language's namespace in a
+ * multi-language project. Its presence is what marks a namespace as a grammar's
+ * type registry rather than an incidental one.
+ */
+const NAMESPACED_AST_TYPE_NAME = 'AstType';
+
+/** Export name of the merged, whole-project binding. */
+const MERGED_EXPORT_NAME = 'astNode';
+
+/**
+ * Emit a module binding {@link makeAstNodeBuilder} to a project's reflection,
+ * once per grammar plus once across all of them.
+ *
+ * **The binding is boilerplate with exactly one degree of freedom** — the type
+ * map — so hand-writing it buys nothing and goes stale the moment a grammar is
+ * added. Generating it is also the only way a narrowed binding can exist at all:
+ * the per-grammar type maps live in namespaces Langium emits only on its
+ * multi-language path, so a single-grammar project gets the merged binding alone
+ * and there is nothing to narrow.
+ *
+ * **A narrowed binding is only as narrow as its grammar's import closure.**
+ * Langium's per-grammar `AstType` lists everything REACHABLE from that grammar,
+ * so where one grammar imports all the others its map equals the project's and
+ * its binding checks nothing the merged one does not. The emitted doc says so at
+ * each declaration rather than promising a guarantee the type map cannot give.
+ *
+ * Answers `false` when the AST source declares no whole-project type alias,
+ * which means the file did not come from `langium generate` and the caller
+ * should report rather than write a module that cannot compile.
+ */
+export function emitAstBuilder(astSource: SourceFile, options: EmitAstBuilderOptions): boolean {
+   const content = buildAstBuilderSource(astSource, options);
+   if (content === undefined) {
+      return false;
+   }
+
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('AST builder is up to date.');
+      return true;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+   return true;
+}
+
+/**
+ * The module text {@link emitAstBuilder} would write, or `undefined` when the
+ * AST source declares no whole-project type alias. Pure over its inputs, so the
+ * emitted shape is testable without touching a filesystem.
+ */
+export function buildAstBuilderSource(astSource: SourceFile, options: EmitAstBuilderOptions): string | undefined {
+   const mergedTypeMap = `${options.languageId}AstType`;
+   if (!astSource.getTypeAlias(mergedTypeMap)) {
+      return undefined;
+   }
+
+   const bindings: BuilderBinding[] = [{ exportName: MERGED_EXPORT_NAME, typeMap: mergedTypeMap }];
+   for (const namespace of findGrammarNamespaces(astSource)) {
+      bindings.push({
+         exportName: builderExportName(namespace),
+         typeMap: `${namespace}.${NAMESPACED_AST_TYPE_NAME}`,
+         namespace
+      });
+   }
+   assertDistinctExportNames(bindings);
+
+   return renderAstBuilder(bindings, {
+      reflectionName: findReflectionConstName(astSource, options.languageId),
+      importPath: relativeImportPath(options.outFile, options.astFile),
+      regenCommand: options.regenCommand
+   });
+}
+
+/**
+ * Namespaces that carry a grammar's type registry, in declaration order.
+ *
+ * Keyed on the nested `AstType` alias rather than on the namespace being
+ * exported, because an adopter's augmentation can add namespaces to the same
+ * file for unrelated reasons and only the ones Langium emits per grammar have
+ * a type map to bind.
+ */
+function findGrammarNamespaces(astSource: SourceFile): string[] {
+   const names: string[] = [];
+   for (const module of astSource.getModules()) {
+      const name = module.getName();
+      if (name && module.getTypeAlias(NAMESPACED_AST_TYPE_NAME)) {
+         names.push(name);
+      }
+   }
+   return names;
+}
+
+/**
+ * `Domain` → `domainNode`. Lower-cases the leading character only, so a grammar
+ * named `OrderFlow` reads as `orderFlowNode` rather than losing its word break.
+ */
+function builderExportName(namespace: string): string {
+   return `${namespace.charAt(0).toLowerCase()}${namespace.slice(1)}Node`;
+}
+
+/**
+ * Two grammars whose names differ only in their leading character collapse to
+ * one export. Emitting anyway would silently drop a binding, so fail with both
+ * names rather than leave the caller to discover it at compile time.
+ */
+function assertDistinctExportNames(bindings: readonly BuilderBinding[]): void {
+   const seen = new Map<string, string>();
+   for (const binding of bindings) {
+      const previous = seen.get(binding.exportName);
+      if (previous !== undefined) {
+         throw new Error(
+            `Cannot emit the AST builder: grammars '${previous}' and '${binding.namespace}' both map to the export ` +
+               `'${binding.exportName}'. Rename one grammar so the generated bindings stay distinct.`
+         );
+      }
+      seen.set(binding.exportName, binding.namespace ?? MERGED_EXPORT_NAME);
+   }
+}
+
+/**
+ * Name of the const holding the project's reflection instance.
+ *
+ * Langium emits `export const reflection = new <LanguageId>AstReflection()`, but
+ * the const is located by its initializer rather than by that name so a renamed
+ * export still resolves. Falls back to the emitted default when no declaration
+ * matches, which keeps the output compiling against a stock Langium file.
+ */
+function findReflectionConstName(astSource: SourceFile, languageId: string): string {
+   const reflectionClass = `${languageId}AstReflection`;
+   for (const declaration of astSource.getVariableDeclarations()) {
+      if (declaration.getInitializer()?.getText().replace(/\s/g, '') === `new${reflectionClass}()`) {
+         return declaration.getName();
+      }
+   }
+   return 'reflection';
+}
+
+/**
+ * Module specifier for the AST file as seen from the generated module's own
+ * directory. Emitted with a `.js` extension and posix separators because the
+ * output is ESM TypeScript, where the specifier names the compiled sibling.
+ */
+function relativeImportPath(outFile: string, astFile: string): string {
+   const relative = path.relative(path.dirname(path.resolve(outFile)), path.resolve(astFile));
+   const posix = relative.split(path.sep).join('/').replace(/\.ts$/, '.js');
+   return posix.startsWith('.') ? posix : `./${posix}`;
+}
+
+function renderAstBuilder(
+   bindings: readonly BuilderBinding[],
+   context: { reflectionName: string; importPath: string; regenCommand: string }
+): string {
+   const imported = [context.reflectionName, ...bindings.map(binding => `type ${binding.namespace ?? binding.typeMap}`)];
+   const out: string[] = [];
+
+   out.push('/******************************************************************************');
+   out.push(' * Generated from the Langium AST — DO NOT EDIT MANUALLY!');
+   out.push(` * ${context.regenCommand}`);
+   out.push(' ******************************************************************************/');
+   out.push('');
+   out.push('/* eslint-disable */');
+   out.push('');
+   out.push("import { makeAstNodeBuilder } from '@hydranium/core';");
+   out.push(`import { ${imported.join(', ')} } from '${context.importPath}';`);
+   out.push('');
+
+   // A single-grammar project has nothing to narrow to, so the merged binding is
+   // simply THE binding there and must not point at a sibling that was not emitted.
+   const narrowed = bindings.some(binding => binding.namespace !== undefined);
+   const guarantee = [
+      ' * Mandatory fields are a type error at the call site, and grammar-declared',
+      ' * containment arrays are materialised from reflection metadata, so a built',
+      ' * node carries `[]` where a cast literal would leave `undefined`.'
+   ];
+
+   for (const binding of bindings) {
+      out.push('/**');
+      if (binding.namespace !== undefined) {
+         out.push(` * AST-node factory narrowed to the '${binding.namespace}' grammar.`);
+         out.push(' *');
+         out.push(' * Narrowed by grammar REACHABILITY, not by ownership: a grammar that');
+         out.push(" * imports another sees that one's types too, so this binding is only as");
+         out.push(` * narrow as '${binding.namespace}'s import closure. Where that closure is the`);
+         out.push(' * whole project, it accepts exactly what the merged binding does and the');
+         out.push(' * choice is documentation rather than a check.');
+         out.push(' *');
+         out.push(...guarantee);
+      } else if (narrowed) {
+         out.push(' * AST-node factory spanning every grammar in this project.');
+         out.push(' *');
+         out.push(' * Prefer the narrowed binding matching the grammar the call site works in:');
+         out.push(" * it rejects a type outside that grammar's import closure, which this one");
+         out.push(' * accepts from anywhere. Reach for this one where a call site genuinely');
+         out.push(' * spans grammars.');
+      } else {
+         out.push(" * AST-node factory for this project's grammar.");
+         out.push(' *');
+         out.push(...guarantee);
+      }
+      out.push(' */');
+      out.push(`export const ${binding.exportName} = makeAstNodeBuilder<${binding.typeMap}>(${context.reflectionName});`);
+      out.push('');
+   }
+
+   return out.join('\n');
+}

package/src/commands/generate-transfer-model-args.ts

@@ -29,6 +29,7 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--ast-file',
    '--augmentation-file',
    '--out-file',
+   '--ast-builder-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -48,7 +49,8 @@ export const GENERATE_TRANSFER_MODEL_VALUE_FLAGS: readonly string[] = GENERATE_T
 export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    'Usage: hydranium-cli generate-transfer-model [options]',
    '',
-   'Generate a serializable transfer-model TypeScript file from a Langium AST. The',
+   'Generate a serializable transfer-model TypeScript file from a Langium AST, and',
+   'optionally an AST-node builder module bound to the same reflection. The',
    'required inputs (--ast-file / --augmentation-file / --out-file) may instead come',
    'from a --config JSON file, and --ast-file can be auto-discovered from a Langium',
    "config's `out` directory. Precedence, highest first: explicit flags, then the",
@@ -67,6 +69,11 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    '                                directory: it treats that directory as exclusively',
    '                                its own, so every `langium generate` reports this',
    '                                file as unexpected and offers to delete it.',
+   '  --ast-builder-file <path>     Also emit an AST-node builder module here: one',
+   '                                makeAstNodeBuilder binding per grammar, plus one',
+   '                                spanning all of them. Omit if nothing constructs',
+   '                                AST nodes. Same restriction as --out-file: keep it',
+   "                                out of langium-cli's own `out` directory.",
    '  --element-type-name <name>    Base element type name in output. Default: TransferElement.',
    '  --terminals-name <name>       Terminals const name in output. Default: ModelTerminals.',
    '  --terminals-source-name <n>   Source-side terminals variable name. Default: <LanguageId>Terminals.',
@@ -120,6 +127,9 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--out-file':
             flags.outFile = next();
             break;
+         case '--ast-builder-file':
+            flags.astBuilderFile = next();
+            break;
          case '--element-type-name':
             flags.elementTypeName = next();
             break;

package/src/commands/generate-transfer-model-config.ts

@@ -9,10 +9,11 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { describeError } from '@hydranium/protocol';
 import type { GenerateTransferModelOptions } from './generate-transfer-model.js';
 
 /** Path-valued option keys — resolved relative to a config/langium-config file's directory. */
-const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile'] as const;
 
 /** Resolve `value` against `baseDir` when it is relative; absolute paths pass through. */
 function resolveAgainst(baseDir: string, value: string): string {
@@ -31,7 +32,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
    try {
       raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read transfer-model config '${configPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read transfer-model config '${configPath}': ${describeError(error)}`);
    }
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
       throw new Error(`Transfer-model config '${configPath}' must be a JSON object.`);
@@ -43,6 +44,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'astFile',
       'augmentationFile',
       'outFile',
+      'astBuilderFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -74,7 +76,7 @@ export function deriveAstFileFromLangiumConfig(langiumConfigPath: string): strin
    try {
       raw = JSON.parse(fs.readFileSync(langiumConfigPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${describeError(error)}`);
    }
    const out = (raw as { out?: unknown })?.out;
    if (typeof out !== 'string') {
@@ -118,6 +120,7 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       astFile: astFile!,
       augmentationFile: augmentationFile!,
       outFile: outFile!,
+      astBuilderFile: pick('astBuilderFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),