@hydranium/core 1.0.0-next.10

package/src/node/socket-launcher.ts

@@ -0,0 +1,210 @@
+/********************************************************************************
+ * 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 { Deferred } from '@hydranium/langium';
+import * as net from 'node:net';
+import type { Disposable, Logger } from '@hydranium/protocol';
+import { createMessageConnection, SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
+import type { MessageConnection } from 'vscode-jsonrpc';
+import type { IntegratedServer } from '../launcher/integrated-server.js';
+
+/**
+ * Construction-time options for {@link startSocketServer}.
+ */
+export interface SocketServerOptions {
+   /**
+    * Port to bind. Default `0` — OS-assigned ephemeral. Resolve the
+    * actual port off {@link StartedSocketServer.port} once `started`
+    * resolves (only then is the address info available).
+    */
+   readonly port?: number;
+   /**
+    * Optional logger. If omitted, the launcher runs silently — the
+    * adopter is expected to surface lifecycle events through their own
+    * logging in {@link OnClientConnection} if needed.
+    */
+   readonly logger?: Logger;
+   /** Tag included in lifecycle log lines. Default `"SocketServer"`. */
+   readonly logTag?: string;
+}
+
+/**
+ * Adopter callback fired per inbound client. Receives the already-
+ * constructed {@link MessageConnection} (created from the socket via
+ * vscode-jsonrpc's `SocketMessageReader`/`SocketMessageWriter`) BEFORE
+ * `connection.listen()` is called — the launcher invokes `listen()`
+ * after the callback returns so adopters that need to register handlers
+ * before message dispatch starts can do so.
+ *
+ * Adopters construct their per-client servers here and return a
+ * {@link Disposable}. The launcher invokes the disposable on socket
+ * close AND on server shutdown — adopters need not register their own
+ * teardown listeners.
+ *
+ * Returning a no-op `{ dispose() {} }` is valid for heads whose servers
+ * self-clean via `connection.onClose` (the framework's `DataServer`
+ * being the canonical example).
+ */
+export type OnClientConnection = (connection: MessageConnection) => Disposable;
+
+/**
+ * Live socket server handle returned by {@link startSocketServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once `listen` resolves
+ *   AND `port` is populated.
+ * - {@link IntegratedServer.stopped} resolves when the underlying
+ *   `net.Server` emits `close`.
+ * - {@link port} is undefined until `started` resolves.
+ * - {@link close} triggers shutdown: disposes all active client
+ *   connections and closes the underlying `net.Server`.
+ */
+export interface StartedSocketServer extends IntegratedServer {
+   readonly port: number | undefined;
+   close(): void;
+}
+
+/**
+ * Start a socket-based protocol head. Wraps `net.createServer` with the
+ * boilerplate adopters used to write per-head: address resolution,
+ * error/close lifecycle, per-client `MessageConnection` construction,
+ * connection tracking, and shutdown cleanup.
+ *
+ * **Multi-client semantics are framework-owned.** The launcher tracks
+ * every accepted connection, invokes the adopter's `onClientConnection`
+ * callback to wire per-client services, and disposes both the returned
+ * adopter disposable AND the underlying `MessageConnection` on socket
+ * close / server shutdown. Adopters keep per-client instance creation
+ * (their server objects) but don't re-implement the tracking machinery.
+ *
+ * The port is only known once {@link StartedSocketServer.started} has
+ * resolved, so announcing it — via {@link publishPortOnLspConnection} —
+ * belongs after that await, not beside the call.
+ */
+export function startSocketServer(options: SocketServerOptions, onClientConnection: OnClientConnection): StartedSocketServer {
+   const port = options.port ?? 0;
+   const logger = options.logger;
+   const tag = options.logTag ?? 'SocketServer';
+   const started = new Deferred<void>();
+   const stopped = new Deferred<void>();
+   const handle: { port: number | undefined } = { port: undefined };
+
+   // Tracks per-connection cleanup: the adopter's returned Disposable for
+   // its per-client server objects PLUS the underlying MessageConnection
+   // (so shutdown drains both at once).
+   const activeConnections: Array<{ connection: MessageConnection; adopterDisposable: Disposable }> = [];
+
+   const netServer = net.createServer(socket => {
+      const connection = createMessageConnection(new SocketMessageReader(socket), new SocketMessageWriter(socket));
+      const adopterDisposable = onClientConnection(connection);
+      const entry = { connection, adopterDisposable };
+      activeConnections.push(entry);
+      // Cleanup hook fires once per connection — covers both socket-side
+      // close and server-shutdown forced close.
+      let disposed = false;
+      const dispose = (): void => {
+         if (disposed) {
+            return;
+         }
+         disposed = true;
+         try {
+            adopterDisposable.dispose();
+         } catch (err) {
+            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${(err as Error)?.message ?? err}`);
+         }
+         connection.dispose();
+         const idx = activeConnections.indexOf(entry);
+         if (idx >= 0) {
+            activeConnections.splice(idx, 1);
+         }
+      };
+      socket.on('close', dispose);
+      connection.onClose(() => dispose());
+      connection.listen();
+   });
+
+   netServer.listen(port);
+   netServer.on('listening', () => {
+      const addressInfo = netServer.address();
+      if (!addressInfo) {
+         logger?.error(`[${tag}] Could not resolve address info. Shutting down.`);
+         started.reject(new Error(`${tag} could not resolve address info`));
+         netServer.close();
+         return;
+      }
+      if (typeof addressInfo === 'string') {
+         logger?.error(`[${tag}] Unexpectedly listening to pipe or domain socket "${addressInfo}". Shutting down.`);
+         started.reject(new Error(`${tag} bound to pipe/domain socket "${addressInfo}", expected TCP`));
+         netServer.close();
+         return;
+      }
+      handle.port = addressInfo.port;
+      logger?.info(`[${tag}] Ready to accept new client requests on port: ${addressInfo.port}`);
+      started.resolve();
+   });
+   netServer.on('error', err => {
+      logger?.error(`[${tag}] Error: ${err.message}`);
+      started.reject(err);
+   });
+   netServer.on('close', () => {
+      // Active client cleanup. Snapshot first since `dispose()` mutates
+      // the array.
+      for (const entry of activeConnections.slice()) {
+         try {
+            entry.adopterDisposable.dispose();
+         } catch (err) {
+            logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${(err as Error)?.message ?? err}`);
+         }
+         entry.connection.dispose();
+      }
+      activeConnections.length = 0;
+      stopped.resolve();
+   });
+
+   return {
+      get port() {
+         return handle.port;
+      },
+      started: started.promise,
+      stopped: stopped.promise,
+      close(): void {
+         netServer.close();
+      }
+   };
+}
+
+/**
+ * The shape the launcher needs from an LSP connection to publish a
+ * port. Matches `vscode-languageserver`'s `Connection.onRequest` —
+ * captured as a structural type here so the launcher doesn't take a
+ * heavy `vscode-languageserver` dep just for the type.
+ */
+export interface LspConnectionLike {
+   onRequest<TParams, TResult>(method: string, handler: (...params: TParams[]) => TResult): Disposable;
+}
+
+/**
+ * Register a `<command>` request handler on the language-server LSP
+ * connection that returns the port. Adopter clients call this command
+ * to discover the head's port after the LSP handshake.
+ *
+ * No-op (returns a `{ dispose() {} }` disposable) when `lspConnection`
+ * is `undefined` — Langium leaves `shared.lsp.Connection` optional and
+ * adopters running headless (no LSP wire) want the same launcher
+ * helpers to work.
+ *
+ * Adopters typically pass `services.shared.lsp.Connection`; both
+ * `services.shared.lsp.Connection?` and the structural `LspConnectionLike`
+ * shape are accepted.
+ */
+export function publishPortOnLspConnection(lspConnection: LspConnectionLike | undefined, command: string, port: number): Disposable {
+   if (!lspConnection) {
+      return { dispose: () => undefined };
+   }
+   return lspConnection.onRequest(command, () => port);
+}

package/src/node/stdio-launcher.ts

@@ -0,0 +1,150 @@
+/********************************************************************************
+ * 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 { Deferred } from '@hydranium/langium';
+import type { Disposable, Logger } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc';
+import { createMessageConnection, StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
+import type { IntegratedServer } from '../launcher/integrated-server.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { initializeWorkspaceProgrammatically, type WorkspaceFolderInput } from '../langium/workspace/initialize-workspace.js';
+
+/** Construction-time options for {@link startStdioServer}. */
+export interface StdioServerOptions {
+   /**
+    * Shared services tree whose workspace is brought up before the first
+    * request is dispatched. Required, because the ordering guarantee this
+    * launcher exists to provide is stated in terms of it.
+    */
+   readonly shared: ServerSharedServicesMinimal;
+   /**
+    * Workspace root(s) to initialize — a filesystem path or a `URI`. Omit when
+    * the caller has already initialized the workspace itself, in which case the
+    * launcher only wires the transport.
+    */
+   readonly workspace?: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>;
+   /**
+    * Optional logger for lifecycle lines. Omitted means silent — note that a
+    * logger writing to **stdout** would corrupt this head's protocol stream, so
+    * anything passed here must sink elsewhere. The framework's own `LspLogger`
+    * writes to stderr when no LSP connection is bound, which is correct here.
+    */
+   readonly logger?: Logger;
+   /** Tag included in lifecycle log lines. Default `"StdioServer"`. */
+   readonly logTag?: string;
+   /**
+    * Input stream carrying inbound JSON-RPC. Default `process.stdin`. Overriding
+    * it is what lets a test drive the launcher over an in-memory duplex pair
+    * instead of spawning a process.
+    */
+   readonly input?: NodeJS.ReadableStream;
+   /** Output stream for outbound JSON-RPC. Default `process.stdout`. */
+   readonly output?: NodeJS.WritableStream;
+}
+
+/**
+ * Live stdio server handle returned by {@link startStdioServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once the workspace is initialized
+ *   AND the connection is listening — i.e. once the head can actually answer.
+ *   It rejects if workspace initialization throws, so a caller awaiting it sees
+ *   a failed startup rather than a server that is listening but empty.
+ * - {@link IntegratedServer.stopped} resolves when the connection closes.
+ */
+export interface StartedStdioServer extends IntegratedServer {
+   /** The underlying connection, for callers wanting fine-grained control. */
+   readonly connection: MessageConnection;
+   /** Dispose the adopter's per-connection state and close the connection. */
+   close(): void;
+}
+
+/**
+ * Start a **stdio**-based protocol head — the transport `hydranium-cli` speaks,
+ * since `query` / `save` / `projects` / `watch` all spawn a server command and
+ * drive JSON-RPC over its stdin/stdout. The socket counterpart is
+ * `startSocketServer`; the two differ more
+ * than the transport swap suggests, and the differences are the reason this is
+ * a launcher rather than four lines in each adopter's entry.
+ *
+ * **One client, not N.** A socket head accepts arbitrarily many connections and
+ * tracks them; a stdio head has exactly one peer — the process that spawned it
+ * — for its whole lifetime. There is no accept loop and no connection registry.
+ *
+ * **Workspace initialization is the launcher's job, and its ordering is the
+ * guarantee.** A stdio data head typically has no LSP connection, so it never
+ * receives `initialize` / `initialized` and nothing else will bring the
+ * workspace up. Worse, the ordering is easy to get subtly wrong: initialization
+ * must complete **before** `connection.listen()`, because nothing reads the
+ * input stream until the reader is attached, so a request that arrives during
+ * startup waits in the pipe buffer. Listening first and initializing
+ * concurrently instead leaves the outcome to whichever internal lock happened
+ * to be held when the request landed — a race, not a guarantee, and one that
+ * shows up as an empty project registry under load rather than as an error.
+ *
+ * The `onConnection` callback runs BEFORE initialization so handlers are
+ * registered first, matching `startSocketServer`'s pre-`listen()` contract.
+ */
+export function startStdioServer(
+   options: StdioServerOptions,
+   onConnection: (connection: MessageConnection) => Disposable
+): StartedStdioServer {
+   const logger = options.logger;
+   const tag = options.logTag ?? 'StdioServer';
+   const started = new Deferred<void>();
+   const stopped = new Deferred<void>();
+
+   const connection = createMessageConnection(
+      new StreamMessageReader(options.input ?? process.stdin),
+      new StreamMessageWriter(options.output ?? process.stdout)
+   );
+   const adopterDisposable = onConnection(connection);
+
+   let disposed = false;
+   const close = (): void => {
+      if (disposed) {
+         return;
+      }
+      disposed = true;
+      try {
+         adopterDisposable.dispose();
+      } catch (err: unknown) {
+         logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      connection.dispose();
+      stopped.resolve();
+   };
+   connection.onClose(() => close());
+
+   const begin = async (): Promise<void> => {
+      if (options.workspace !== undefined) {
+         logger?.info(`[${tag}] Initializing workspace`);
+         await initializeWorkspaceProgrammatically(options.shared, options.workspace);
+      }
+      // Only now attach the reader — see the ordering note in the doc above.
+      connection.listen();
+      logger?.info(`[${tag}] Listening on stdio`);
+   };
+
+   begin().then(
+      () => started.resolve(),
+      (err: unknown) => {
+         // A failed startup must not leave a half-live head: report it on
+         // `started` and tear the connection down rather than listening over an
+         // uninitialized workspace.
+         logger?.error(`[${tag}] Startup failed: ${err instanceof Error ? err.message : String(err)}`);
+         started.reject(err);
+         close();
+      }
+   );
+   // `started` is always observed internally, so a caller that ignores it can
+   // never crash the process with an unhandled rejection.
+   void started.promise.catch(() => undefined);
+
+   return { started: started.promise, stopped: stopped.promise, connection, close };
+}

package/src/node/validate-workspace.ts

@@ -0,0 +1,133 @@
+/********************************************************************************
+ * 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 LangiumDocument, type URI } from '@hydranium/langium';
+import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+
+/** A validation diagnostic's severity, as a stable lowercase string for the JSON contract. */
+export type ValidationSeverity = 'error' | 'warning' | 'info' | 'hint';
+
+/**
+ * One validation problem, flattened to a serialisable shape. This is the JSON
+ * contract `hydranium-cli validate --json` emits, deliberately independent of the
+ * `vscode-languageserver` {@link Diagnostic} type so CI tooling reads a stable
+ * schema and the CLI never needs a runtime `@hydranium/core` dependency.
+ */
+export interface ValidationFinding {
+   /** Workspace-relative path of the document the problem was reported on. */
+   uri: string;
+   severity: ValidationSeverity;
+   message: string;
+   /** 0-based line of the diagnostic range start (add 1 for editor display). */
+   line: number;
+   /** 0-based character of the diagnostic range start (add 1 for editor display). */
+   character: number;
+   /** The diagnostic `code`, when the rule set one. */
+   code?: string | number;
+   /** The diagnostic `source`, when the rule set one. */
+   source?: string;
+}
+
+/** Per-severity tally across the whole workspace — drives the exit code and the summary line. */
+export interface ValidationCounts {
+   error: number;
+   warning: number;
+   info: number;
+   hint: number;
+}
+
+/** The full result of a headless workspace validation. */
+export interface WorkspaceValidationResult {
+   /** Number of `LangiumDocument`s in the built workspace. */
+   documents: number;
+   /** Every problem found, grouped contiguously by document, in the order the documents were given. */
+   findings: ValidationFinding[];
+   /** Per-severity totals over {@link findings}. */
+   counts: ValidationCounts;
+}
+
+/** Options for {@link validateWorkspace}. */
+export interface ValidateWorkspaceOptions {
+   /**
+    * Create the language's shared services in-process. This is the only
+    * language-specific input — a head passes its own `create<Lang>Services(fileSystem)`.
+    */
+   createServices: () => { shared: ServerSharedServicesMinimal };
+   /** Workspace root (filesystem path or file URI) to build and validate. */
+   workspace: string;
+}
+
+/** Map a `vscode-languageserver` severity to the stable string. Unset → `error` (fail-safe for a CI gate). */
+function severityLabel(severity: DiagnosticSeverity | undefined): ValidationSeverity {
+   switch (severity) {
+      case DiagnosticSeverity.Warning:
+         return 'warning';
+      case DiagnosticSeverity.Information:
+         return 'info';
+      case DiagnosticSeverity.Hint:
+         return 'hint';
+      default:
+         // DiagnosticSeverity.Error, or an omitted severity — treat as an error so
+         // a rule that forgets to set one still blocks the gate rather than passing silently.
+         return 'error';
+   }
+}
+
+/**
+ * Flatten each document's `diagnostics` into a {@link WorkspaceValidationResult}.
+ * Pure over its inputs (documents + a URI-to-relative-path mapper) so it unit-tests
+ * without booting a grammar; {@link validateWorkspace} is the thin boot-and-build wrapper.
+ */
+export function collectValidationResult(
+   documents: readonly LangiumDocument[],
+   wsRelativePath: (uri: URI) => string
+): WorkspaceValidationResult {
+   const findings: ValidationFinding[] = [];
+   const counts: ValidationCounts = { error: 0, warning: 0, info: 0, hint: 0 };
+   for (const document of documents) {
+      const relativeUri = wsRelativePath(document.uri);
+      for (const diagnostic of (document.diagnostics ?? []) as Diagnostic[]) {
+         const severity = severityLabel(diagnostic.severity);
+         counts[severity] += 1;
+         findings.push({
+            uri: relativeUri,
+            severity,
+            // LSP 3.18 allows a `MarkupContent` message; this report is a
+            // line-oriented CI artifact, so take its plain-text rendering.
+            message: Diagnostic.getMessageString(diagnostic),
+            line: diagnostic.range.start.line,
+            character: diagnostic.range.start.character,
+            code: diagnostic.code,
+            source: diagnostic.source
+         });
+      }
+   }
+   return { documents: documents.length, findings, counts };
+}
+
+/**
+ * Headless workspace validation — the browser-/socket-free counterpart to the
+ * diagnostics an editor session publishes. Boots a head's Langium services
+ * in-process via {@link ValidateWorkspaceOptions.createServices}, builds every
+ * document to `Validated` (which runs the language's validation checks), then
+ * collects the diagnostics into a serialisable {@link WorkspaceValidationResult}.
+ *
+ * Backs `hydranium-cli validate`, whose non-zero exit on errors makes it a CI
+ * gate. Like the other headless harnesses the only language-specific input is the
+ * service factory, so the framework code stays head-neutral. The build is the
+ * standard eager pipeline — identical to what those sibling harnesses run.
+ */
+export async function validateWorkspace(options: ValidateWorkspaceOptions): Promise<WorkspaceValidationResult> {
+   const { shared } = options.createServices();
+   await buildWorkspaceProgrammatically(shared, options.workspace);
+   const documents = shared.workspace.LangiumDocuments.all.toArray();
+   return collectValidationResult(documents, uri => shared.workspace.WorkspaceManager.wsRelativePath(uri));
+}

package/src/node/write-lock-scope-node.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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 { AsyncLocalStorage } from 'node:async_hooks';
+import { type WriteLockScope, setWriteLockScope } from '../langium/workspace/write-lock-scope.js';
+
+const storage = new AsyncLocalStorage<true>();
+
+/**
+ * `node:async_hooks`-backed {@link WriteLockScope}.
+ *
+ * `AsyncLocalStorage` is the right primitive rather than a plain module-level
+ * boolean: the lock's action is async, and a flag set around it would report
+ * "inside" for every other task interleaved on the event loop while that action
+ * awaits — which is most of them. The store follows the async stack instead, so
+ * only code actually descended from the action sees it.
+ */
+export const nodeWriteLockScope: WriteLockScope = {
+   run<T>(fn: () => T): T {
+      return storage.run(true, fn);
+   },
+   isInside(): boolean {
+      return storage.getStore() === true;
+   }
+};
+
+/**
+ * Install the Node write-lock scope tracker, enabling reentrancy detection on the
+ * model facade. Idempotent. Called once at `@hydranium/core/node` load, so any
+ * Node host that imports the entry gets the detection for free; a browser bundle
+ * imports only `.` and keeps the inert default.
+ */
+export function installNodeWriteLockScope(): void {
+   setWriteLockScope(nodeWriteLockScope);
+}

package/src/testing/ast-snapshot.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Structural AST snapshots for serializer round-trip testing.
+ *
+ * # The idea
+ *
+ * Byte-stability (the golden corpus) proves the serializer's *output format*
+ * is pinned, but not that serialization *preserves meaning*. The complementary
+ * guarantee is the round trip: parse some source, serialize the resulting
+ * model back to text, parse that text again — the two models must be the same.
+ * If they are, no semantic content was lost or invented in the trip through
+ * text, independent of whitespace, member ordering, or dropped comments.
+ *
+ * # Why a snapshot, not the live AST
+ *
+ * You cannot `expect(ast2).toEqual(ast1)` on two live Langium ASTs:
+ * - `$container` (and friends) make every node cyclic — a deep-equal walk
+ *   never terminates.
+ * - `$cstNode` carries source offsets that legitimately differ once text has
+ *   been re-serialized and re-parsed, so it is noise for a semantic compare.
+ * - a `Reference` holds a resolved `ref` back-pointer into the other tree;
+ *   only its textual `$refText` is grammar content.
+ *
+ * {@link makeAstSnapshot} projects a node onto a plain, acyclic, JSON-like
+ * value that keeps exactly the grammar-derived shape — node `$type`s, their
+ * own properties, references reduced to `{ $refText }` — and drops the derived
+ * placement/parse metadata and computed extensions. Two snapshots then compare
+ * cleanly with `toEqual`, and that comparison means "same semantic model".
+ */
+
+import { isAstNode, isReference } from '@hydranium/langium';
+
+/**
+ * A plain, JSON-like structural view of an AST sub-tree — references reduced
+ * to `{ $refText }`, every Langium-internal and computed-extension field
+ * stripped. Cycle-free by construction, so it compares cleanly with
+ * `expect(...).toEqual(...)`.
+ */
+export type AstSnapshot = unknown;
+
+/**
+ * Project an AST node (or any value reachable from one) onto a comparable
+ * {@link AstSnapshot} that captures only the grammar-derived shape.
+ *
+ * Built for round-trip assertions: the snapshot of a model re-parsed from its
+ * own serialized text deep-equals the snapshot of the original iff
+ * serialization preserved the semantic model, independent of formatting (see
+ * the module comment for why a snapshot is needed rather than a direct compare
+ * of the live ASTs).
+ *
+ * What it keeps and what it drops:
+ * - **`Reference`** (`$refText` + `ref`) → `{ $refText }`. The resolution
+ *   target is positional noise; the textual name is the grammar content.
+ * - **`$type`** is kept (it identifies the node); every other `$`-prefixed
+ *   field (`$container`, `$containerProperty`, `$containerIndex`, `$cstNode`,
+ *   `$document`, …) is dropped — all are derived placement/parse metadata.
+ * - **`_`-prefixed fields** — the AST-extension computed properties — are
+ *   dropped: they are derived at build time, not part of what a serializer
+ *   round-trips.
+ * - Arrays recurse element-wise; primitives pass through unchanged.
+ */
+export function makeAstSnapshot(value: unknown): AstSnapshot {
+   if (isReference(value)) {
+      return { $refText: value.$refText };
+   }
+   if (Array.isArray(value)) {
+      return value.map(makeAstSnapshot);
+   }
+   if (isAstNode(value)) {
+      const snapshot: Record<string, unknown> = { $type: value.$type };
+      for (const [key, child] of Object.entries(value)) {
+         if (key.startsWith('$') || key.startsWith('_')) {
+            continue;
+         }
+         snapshot[key] = makeAstSnapshot(child);
+      }
+      return snapshot;
+   }
+   return value;
+}