@hydranium/core 1.0.0-next.10

package/src/langium/workspace/persistent-file-system-provider.ts

@@ -0,0 +1,287 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
+import { type FileSystemSeed, InMemoryFileSystemProvider, type InMemoryFileSystemOptions } from './in-memory-file-system-provider.js';
+
+/**
+ * An asynchronous key/value store a {@link PersistentFileSystemProvider} mirrors
+ * its writes into and is restored from.
+ *
+ * # Why a store behind the map, rather than a provider over the store
+ *
+ * Langium's `FileSystemProvider` requires SYNCHRONOUS reads — `statSync`,
+ * `existsSync`, `readFileSync`, `readDirectorySync` — and the stores a browser
+ * offers cannot answer synchronously: `IndexedDB` has no sync API at all, and
+ * OPFS has synchronous file handles but still enumerates a directory
+ * asynchronously, so even there a directory index has to be held in memory. A
+ * store therefore cannot back the provider directly, whatever it is. The map
+ * stays the read path and the store is a write-through mirror loaded once,
+ * before the server starts.
+ *
+ * # A key here is a SEED key, not a URI
+ *
+ * Keys are exactly {@link FileSystemSeed} keys: relative to the provider's
+ * `rootUri` when it has one, an absolute URI string when it does not. Two
+ * consequences worth having — a stored workspace reloads under a different
+ * `rootUri` than it was written from, and the seed and the store are the same
+ * key space, so restoring is an overlay rather than a translation step only one
+ * side would remember.
+ *
+ * # Failure is the caller's to see
+ *
+ * Every method may reject, and the provider propagates a rejection out of
+ * `writeFile` rather than absorbing it — a save that reports success for content
+ * no store holds is the failure this seam exists to make impossible. Browser
+ * storage really does fail: a quota is finite, and the user agent may EVICT the
+ * whole origin's storage under pressure or on a "clear site data".
+ */
+export interface FileSystemStore {
+   /**
+    * Everything the store holds. An empty record is the first-visit answer and
+    * not an error, which is what makes the provider's seed the baseline.
+    */
+   load(): Promise<FileSystemSeed>;
+   /**
+    * Store `content` under `path`, replacing any previous content.
+    *
+    * `content` is OPAQUE and must be stored byte for byte: the provider also
+    * writes a deletion marker through here, so a store that validated or
+    * normalised what it was given would turn a delete into a file whose content
+    * is the marker.
+    */
+   write(path: string, content: string): Promise<void>;
+   /** Drop `path`. Storing nothing there already is not an error. */
+   remove(path: string): Promise<void>;
+}
+
+/**
+ * The stored VALUE that means "deleted", as opposed to content.
+ *
+ * NUL-wrapped so no document can be taken for one: a file whose entire content
+ * is this exact string would be restored as a deletion, and text a grammar can
+ * parse holds no NUL. Deliberately not exported — a store must treat it as
+ * opaque content, and a host that could recognise it would be tempted to.
+ */
+const TOMBSTONE = '\u0000hydranium:deleted\u0000';
+
+/** Options for {@link PersistentFileSystemProvider} and {@link persistentFileSystem}. */
+export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
+   /** The store writes mirror into and {@link restored} content came out of. */
+   store: FileSystemStore;
+   /**
+    * Content already read out of {@link store}, applied OVER
+    * {@link InMemoryFileSystemOptions.seed} at construction.
+    *
+    * Filled by {@link persistentFileSystem}, which is the supported way in: the
+    * provider is constructed synchronously by the services factory, so a load
+    * cannot happen inside it.
+    */
+   restored?: FileSystemSeed;
+}
+
+/**
+ * An {@link InMemoryFileSystemProvider} whose writes survive the page: the map
+ * is still the read path, and every write is mirrored into an asynchronous
+ * {@link FileSystemStore} that the next start is restored from.
+ *
+ * # The seed is the baseline and the store is the delta
+ *
+ * A restored entry wins over the seed for the same key; a seeded file the store
+ * has never heard of is served from the seed. So a first visit is the seed
+ * exactly, a returning visit is the seed with the edits laid over it, and a file
+ * the host adds to its seed later appears for a visitor who already has stored
+ * content — which whole-store precedence would have hidden until they cleared
+ * their storage.
+ *
+ * # Deleting a seeded file writes a marker, because dropping its entry would not
+ *
+ * A delta over a baseline cannot express absence by omission: removing the
+ * stored entry for a seeded file returns it to its seeded content on the next
+ * restore, which is a deletion that undoes itself. So {@link deleteFile} stores
+ * a TOMBSTONE for a path the seed carries, and restoring one applies it as a
+ * deletion rather than as content. Re-creating the file is an ordinary write over
+ * the marker, so nothing has to un-mark it.
+ *
+ * A path the seed does NOT carry needs no marker — absence from the store is
+ * already absence — so its entry is removed instead, which is what keeps a host
+ * that creates and deletes scratch files from growing the store forever.
+ *
+ * The marker is a reserved VALUE rather than a reserved key, and that is for the
+ * store's sake: a key is a seed-space path by contract, and a store may map keys
+ * to real filenames, where a reserved key prefix would ask it to create a file
+ * whose name is not a path. As a value it needs nothing from any store. Two
+ * consequences worth knowing: a host that reads the store directly — to count
+ * what is held, say — sees marker entries among the content ones and cannot tell
+ * them apart; and a document whose ENTIRE content is the marker string would be
+ * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
+ * can parse is not.
+ *
+ * # A registered virtual document still wins
+ *
+ * `readFileSync` consults the virtual-document seam before the map, so a stdlib
+ * contributed in code keeps answering for its URI whether or not the store holds
+ * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
+ * that URI from losing the stdlib.
+ *
+ * # What it deliberately does not answer
+ *
+ * The store is scoped to the ORIGIN, not to the page: two pages on the same
+ * origin share it, and the user agent may evict it entirely. Both are properties
+ * of browser storage rather than of this class, and neither is worth a stub —
+ * eviction presents as a first visit, which is a state this provider is
+ * correct in.
+ */
+export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
+   protected readonly store: FileSystemStore;
+   /**
+    * The map-key prefix store keys are relative to, WITH its trailing
+    * separator, or `undefined` when store keys are absolute URIs.
+    */
+   protected readonly storeRoot?: string;
+   /**
+    * The seed's paths, in STORE-key space rather than as the record was written.
+    *
+    * Normalised on the way in for the same reason restoring is: a seed key and
+    * the key derived from a URI disagree for a percent-encodable path, so a raw
+    * `Object.keys` set would call `a b.x` unseeded and remove its entry instead
+    * of marking it — a deletion that quietly undoes itself on the next load.
+    */
+   protected readonly seededPaths: ReadonlySet<string>;
+
+   constructor(services: ServerSharedServicesMinimal, options: PersistentFileSystemOptions) {
+      super(services, options);
+      this.store = options.store;
+      this.storeRoot = options.rootUri === undefined ? undefined : `${this.fileKey(options.rootUri)}/`;
+      this.seededPaths = new Set(Object.keys(options.seed ?? {}).map(path => this.storeKey(this.storeUri(path))));
+      for (const [path, content] of Object.entries(options.restored ?? {})) {
+         // `super.*`, so restoring does not mirror straight back into the store
+         // it just came from — a write-back on every start, and one that would
+         // resurrect an entry the store had legitimately dropped.
+         //
+         // Applied AFTER the seed and through the same key normalisation, which
+         // is what makes "restored wins" hold for a key the two spell
+         // differently (`a b.x` against `a%20b.x`) instead of depending on the
+         // insertion order of a merged record.
+         const uri = this.storeUri(path);
+         if (content === TOMBSTONE) {
+            super.deleteFile(uri);
+         } else {
+            super.setFile(uri, content);
+         }
+      }
+   }
+
+   /**
+    * The sync twin, mirrored without waiting.
+    *
+    * It has no way to report a store failure to its caller, so the tracer is the
+    * only channel it has — which is why {@link writeFile}, the path a save
+    * actually takes, awaits instead.
+    */
+   override setFile(uri: URI, content: string): void {
+      super.setFile(uri, content);
+      this.persist(uri, content).catch((error: unknown) => this.reportStoreFailure('store', uri, error));
+   }
+
+   /**
+    * Write through to the store and REJECT if it refuses.
+    *
+    * A quota failure or an evicted origin has to reach the client that asked for
+    * the save: the alternative is a page that reports a saved workspace and
+    * reloads without it, which is the same shape as persistence working.
+    *
+    * `super.setFile` rather than `this.setFile`, so the awaited mirror below is
+    * the only one — the override would fire a second, unawaited write for the
+    * same content.
+    */
+   override async writeFile(uri: URI, content: string): Promise<void> {
+      super.setFile(uri, content);
+      await this.persist(uri, content);
+   }
+
+   override deleteFile(uri: URI): void {
+      super.deleteFile(uri);
+      this.forget(uri).catch((error: unknown) => this.reportStoreFailure('forget', uri, error));
+   }
+
+   /** The absolute URI a store-space `path` addresses. */
+   protected storeUri(path: string): URI {
+      return URI.parse(this.storeRoot === undefined ? path : `${this.storeRoot}${path}`);
+   }
+
+   /** Mirror one write. `async` so a bad key rejects rather than throwing at the call site. */
+   protected async persist(uri: URI, content: string): Promise<void> {
+      await this.store.write(this.storeKey(uri), content);
+   }
+
+   /**
+    * Mirror one deletion: a tombstone where the seed would otherwise bring the
+    * file back, a plain removal where it would not. `async` for the same reason
+    * as {@link persist}.
+    */
+   protected async forget(uri: URI): Promise<void> {
+      const path = this.storeKey(uri);
+      if (this.seededPaths.has(path)) {
+         await this.store.write(path, TOMBSTONE);
+      } else {
+         await this.store.remove(path);
+      }
+   }
+
+   /**
+    * The store key for `uri`, in the seed's key space.
+    *
+    * Throws for a URI outside `rootUri` rather than keying it absolutely beside
+    * the relative ones: a store holding both spellings restores under neither,
+    * and a host writing outside the workspace it declared has a wiring fault
+    * worth hearing about.
+    */
+   protected storeKey(uri: URI): string {
+      const key = this.fileKey(uri);
+      if (this.storeRoot === undefined) {
+         return key;
+      }
+      if (!key.startsWith(this.storeRoot)) {
+         throw new Error(`Cannot persist ${uri.toString()}: outside the store root ${this.storeRoot}`);
+      }
+      return key.slice(this.storeRoot.length);
+   }
+
+   protected reportStoreFailure(operation: string, uri: URI, error: unknown): void {
+      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+   }
+}
+
+/**
+ * Restore `options.store` and bind a {@link PersistentFileSystemProvider} over
+ * it, spread into the services context exactly where a Node host spreads
+ * `NodeFileSystem`.
+ *
+ * **It is asynchronous, and that is the ordering contract rather than an
+ * implementation detail.** The provider's reads are synchronous, so the stored
+ * workspace must be in the map before anything reads it — and a `hydrate()`
+ * method on the provider could not enforce that, because awaiting one after the
+ * transport exists is already too late: a `BrowserMessageReader` starts its port
+ * on construction but fires into an emitter with no listener until
+ * `startLanguageServer` calls `listen`, so an `initialize` arriving during the
+ * await is DROPPED — no error, no reply, a client that waits forever. Loading
+ * here, before the services and therefore before the connection exist, makes
+ * that unrepresentable rather than documented.
+ */
+export async function persistentFileSystem(options: PersistentFileSystemOptions): Promise<{
+   fileSystemProvider: (services: unknown) => WritableFileSystemProvider;
+}> {
+   const restored = await options.store.load();
+   return {
+      fileSystemProvider: serverSharedFactory(services => new PersistentFileSystemProvider(services, { ...options, restored }))
+   };
+}

package/src/langium/workspace/synthetic.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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 Mutable } from '@hydranium/protocol';
+import { type AstNode, AstUtils } from '@hydranium/langium';
+
+// The `$synthetic` `AstNode` type augmentation lives in `@hydranium/langium`
+// (the langium chokepoint); it arrives here ambiently via that dependency.
+// This module owns the *behaviour* of the synthetic-node concept — the marker
+// helpers below and the validation-skip default that reads them.
+//
+// This is the NODE-provenance axis: a synthetic node is one not authored by
+// the user — synthesized in code (a stdlib element) or by projection (a mirror
+// of an inherited member). It is distinct from the *document* axis, where a
+// virtual document is one with no backing file. The two are orthogonal: a
+// synthetic node can live in a real file, and a virtual document can hold
+// non-synthetic nodes.
+
+/**
+ * Mark `node` as synthetic. Returns the node for fluent chaining.
+ *
+ * Opting into the synthetic marker drives behaviour changes downstream
+ * — most notably, the framework's
+ * `HydraniumDocumentValidator.shouldSkipValidation` default
+ * skips marked nodes (unless `validateSyntheticNodes` is enabled),
+ * short-circuiting validation for mirrors and stdlib content. Adopters
+ * who want a synthetic node validated normally simply do not mark it.
+ */
+export function markSynthetic<T extends AstNode>(node: T): T {
+   (node as Mutable<T>).$synthetic = true;
+   return node;
+}
+
+/**
+ * Walk an AST tree rooted at `root` and {@link markSynthetic mark}
+ * every node. Use when building a stdlib / library document where
+ * every node should opt into skip-validation semantics in one stroke.
+ *
+ * For partial marking (some nodes mirrored, some validated normally),
+ * call {@link markSynthetic} on the specific nodes instead.
+ */
+export function markSyntheticTree(root: AstNode): void {
+   for (const node of AstUtils.streamAst(root)) {
+      markSynthetic(node);
+   }
+}
+
+/**
+ * True iff `node` has been explicitly marked synthetic via
+ * {@link markSynthetic} / {@link markSyntheticTree}. The check is a
+ * pure flag read — the URI scheme of the containing document does
+ * not influence this predicate (see `isVirtualUri` for the separate
+ * document-identity axis).
+ */
+export function isSyntheticNode(node: AstNode): boolean {
+   return node.$synthetic === true;
+}

package/src/langium/workspace/virtual-document.ts

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+
+/**
+ * URI scheme for virtual documents — LangiumDocuments that have no backing
+ * file on disk (a language's stdlib, library types, built-in definitions,
+ * mirrors, generated views). Chosen so it cannot collide with on-disk `file:`
+ * URIs, and so the framework's FileSystemProvider can recognise and serve them
+ * on re-read (see {@link serveVirtualDocument}).
+ */
+export const VIRTUAL_SCHEME = 'virtual';
+
+/**
+ * Build a URI for a virtual document — one whose content is provided in code
+ * rather than read from disk, either as a parsed string
+ * (`LangiumDocumentFactory.fromString`) or a code-built AST
+ * (`LangiumDocumentFactory.fromModel`).
+ *
+ * The URI uses the {@link VIRTUAL_SCHEME} scheme. The first segment carries
+ * contributor identity for diagnostics, telemetry, and "go to source" UI;
+ * additional segments scope sub-documents within one contributor.
+ *
+ * Pair with a `LangiumDocumentFactory` to construct a document whose content
+ * lives in memory. The resulting document is suitable as the `document`
+ * argument to the tier factories on `HydraniumAstNodeDescriptionProvider`
+ * (`createLocal` / `createProject` / `createPublic` / `createUniversal`).
+ *
+ * # End the URI with a registered file extension
+ *
+ * Called with a contributor and no further segments this yields
+ * `virtual:<contributor>`, which has no extension and so matches no registered
+ * language — a trap. Every per-language service is resolved per URI, and a
+ * virtual document is never open in `TextDocuments`, so the declared-languageId
+ * lookup rung cannot serve it either: the document is indexed but inert,
+ * contributing nothing to the scopes it was written to populate, with no error
+ * anywhere. Pass the extension as the last segment,
+ * `virtualUri(contributor, 'name.<ext>')`. `HydraniumWorkspaceManager` warns
+ * when a seeded additional document fails to route, which is where this
+ * usually surfaces.
+ *
+ * # Relationship to the `$synthetic` node marker
+ *
+ * The URI scheme tags the *document* as not-from-disk; the `$synthetic` node
+ * marker (see `markSynthetic` / `isSyntheticNode`) tags an individual *node* as
+ * not user-authored. A virtual document may contain non-synthetic nodes and
+ * vice versa.
+ *
+ * Both axes are read by `HydraniumDocumentValidator`, at different
+ * granularities: the scheme skips the WHOLE document
+ * (`validateVirtualDocuments`, default `false`, so the walk is avoided
+ * entirely), the marker skips a node and its children
+ * (`validateSyntheticNodes`, default `false`).
+ */
+export function virtualUri(contributor: string, ...segments: string[]): URI {
+   const tail = segments.length > 0 ? '/' + segments.join('/') : '';
+   return URI.parse(`${VIRTUAL_SCHEME}:${contributor}${tail}`);
+}
+
+/** True iff `uri` uses the {@link VIRTUAL_SCHEME} scheme produced by {@link virtualUri}. */
+export function isVirtualUri(uri: URI | string): boolean {
+   const scheme = typeof uri === 'string' ? URI.parse(uri).scheme : uri.scheme;
+   return scheme === VIRTUAL_SCHEME;
+}
+
+/**
+ * Serve the text of a registered virtual document, or `undefined` when `uri`
+ * is not virtual or no document is registered for it (so a FileSystemProvider
+ * delegates to its real backing).
+ *
+ * The framework's FileSystemProvider defaults call this at the top of
+ * `readFile` / `readFileSync` so a virtual document survives a re-read:
+ * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
+ * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
+ * text comes from the registered document — the original source for a
+ * `fromString` document, or the serialized form retained by the framework's
+ * `fromModel` (which fills in the text Langium leaves empty). No serializer is
+ * consulted here; the text is already on the document.
+ */
+export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined {
+   if (!isVirtualUri(uri)) {
+      return undefined;
+   }
+   const document = services.workspace.LangiumDocuments.getDocument(uri);
+   return document ? document.textDocument.getText() : undefined;
+}

package/src/langium/workspace/write-lock-scope.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
+ ********************************************************************************/
+
+/**
+ * Tracks whether the currently-executing code is running inside a holder of the
+ * workspace WRITE lock.
+ *
+ * The question matters because `WorkspaceLock` is not reentrant: acquiring the
+ * write lock calls `cancelWrite()` on the running holder, so a caller that
+ * reaches the model facade from inside a build has its ENCLOSING build cancelled
+ * and may then stall in the follow-up phase wait. That is a latent deadlock with
+ * no static signature — the call looks ordinary at every layer — so the only way
+ * to surface it is to know, at the moment of acquisition, whether the lock is
+ * already held further up the same async stack.
+ *
+ * Answering it needs async-context propagation, which has no browser-neutral
+ * implementation: Node's `AsyncLocalStorage` is a `node:async_hooks` import (so
+ * it cannot appear on the portable `.` entry, which `check:neutral` gates), and
+ * TC39's `AsyncContext` is unshipped. Hence the same seam shape the log file-tee
+ * uses: this module declares the contract and defaults to inert, and
+ * `@hydranium/core/node` installs a real implementation at entry load. A browser
+ * bundle therefore gets NO detection rather than a broken approximation, which
+ * is the right degradation — the reentrant shape is a server-side build concern,
+ * and a false negative costs the pre-existing stall while a false positive would
+ * reject a legitimate write.
+ */
+export interface WriteLockScope {
+   /** Run `fn` marked as executing inside a write-lock holder. */
+   run<T>(fn: () => T): T;
+   /** Whether the caller is already inside a {@link run} scope. */
+   isInside(): boolean;
+}
+
+let writeLockScope: WriteLockScope | undefined;
+
+/** Install (or clear, with `undefined`) the write-lock scope tracker. Idempotent. */
+export function setWriteLockScope(scope: WriteLockScope | undefined): void {
+   writeLockScope = scope;
+}
+
+/**
+ * Run `fn` inside the write-lock scope, if a tracker is installed. Without one
+ * this is a plain call, so the wrapper is safe to apply unconditionally on the
+ * neutral path.
+ */
+export function runInWriteLockScope<T>(fn: () => T): T {
+   return writeLockScope ? writeLockScope.run(fn) : fn();
+}
+
+/**
+ * Whether the caller is executing inside a workspace write-lock holder.
+ *
+ * Returns `false` when no tracker is installed, so every guard reading this
+ * fails OPEN — an un-instrumented host keeps its current behaviour rather than
+ * gaining spurious rejections.
+ */
+export function isInsideWriteLock(): boolean {
+   return writeLockScope?.isInside() ?? false;
+}
+
+/**
+ * Thrown when the model facade is reached from inside a workspace write-lock
+ * holder — typically an integrity rule or build-phase pass writing through
+ * `ModelService.update` / `save` / `rebuild` during a build.
+ *
+ * Named rather than a bare `Error` because the remedy is specific and worth
+ * pointing at: either move the write out of the build (integrity rules that
+ * persist repairs should write through `FileSystemProvider.writeFile`, which
+ * takes no lock), or set `ModelServiceOptions.serializeBuilds: false` to accept
+ * unserialised builds in exchange for the reentrancy.
+ */
+export class ReentrantWriteLockError extends Error {
+   constructor(readonly uri: string) {
+      super(
+         `Model facade reached for '${uri}' from inside a workspace write-lock holder. ` +
+            'Acquiring the write lock would cancel the enclosing build and may stall this call. ' +
+            'Write through FileSystemProvider.writeFile from a build-phase pass, or set ' +
+            'ModelServiceOptions.serializeBuilds: false to opt out of build serialisation.'
+      );
+      this.name = 'ReentrantWriteLockError';
+   }
+}

package/src/launcher/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './integrated-server.js';
+// Only the transport-agnostic handle belongs here: `socket-launcher` pulls
+// `node:net` and therefore ships from `@hydranium/core/node` instead.

package/src/launcher/integrated-server.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Lifecycle handle for a protocol-head server (socket-based, stdio-based,
+ * or otherwise) that the adopter starts during language-server bootstrap.
+ *
+ * The two promises encode the canonical two-phase startup pattern:
+ * - {@link started} resolves once the head is accepting traffic — for a
+ *   socket server, this means `net.Server.listen` resolved AND the bound
+ *   port is known. Adopter bootstrap code awaits this before publishing
+ *   the port and announcing readiness over the LSP connection.
+ * - {@link stopped} resolves once the head has shut down cleanly — used
+ *   primarily by tests waiting for tidy teardown.
+ *
+ * Either promise may reject if startup or shutdown encounters an error
+ * the head can't recover from.
+ */
+export interface IntegratedServer {
+   readonly started: Promise<void>;
+   readonly stopped: Promise<void>;
+}