@hydranium/core 1.0.0-next.10

package/src/testing/make-test-services.ts

@@ -0,0 +1,356 @@
+/********************************************************************************
+ * 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 Clock,
+   DefaultTracer,
+   type Logger,
+   NoopLogger,
+   type Project,
+   SystemClock,
+   type Tracer,
+   type TransferDiagnostic,
+   type TransferElement
+} from '@hydranium/protocol';
+import type { Harness } from '@hydranium/protocol/testing';
+import { type AstNode, type AstNodeDescription, type WorkspaceLock } from '@hydranium/langium';
+import type { ModelService, ModelServiceOptions } from '../langium/model-service/model-service.js';
+import type { ServerSharedServices } from '../langium/module.js';
+import { TransferEncoder } from '../langium/transfer/transfer-encoder.js';
+import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
+import type { FakeDocumentOptions } from './fake-document.js';
+import { makeStubDocumentBuilder, type StubDocumentBuilder } from './stub-document-builder.js';
+import { makeStubIndexManager, type StubIndexManager } from './stub-index-manager.js';
+import { makeStubLangiumDocuments, type StubLangiumDocuments } from './stub-langium-documents.js';
+import { makeStubModelService } from './stub-model-service.js';
+import { makeStubAstDocumentManager, type StubAstDocumentManager } from './stub-ast-document-manager.js';
+import { makeStubProjectManager, type StubProjectManager } from './stub-project-manager.js';
+import { makeStubSelfSaveRegistry, type StubSelfSaveRegistry } from './stub-self-save-registry.js';
+import { makeStubHydraniumTextDocuments, type StubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
+import { makeStubServiceRegistry, type StubLanguageDescriptor, type StubServiceRegistry } from './stub-service-registry.js';
+import { makeStubWritableFileSystem, type StubWritableFileSystem } from './stub-writable-file-system.js';
+
+/**
+ * Honest shape of the `services` tree assembled by {@link makeTestServices}.
+ * Captures exactly the slots the bundle binds — narrower than the full
+ * {@link ServerSharedServices} that production code consumes, with no
+ * placeholder for slots that don't appear in the literal (`AstNodeLocator`,
+ * `WorkspaceManager`, etc.). The boundary cast from this type
+ * to `ServerSharedServices` in {@link makeTestServices} is therefore the
+ * single named place where the "stub stands in for the full service tree"
+ * assertion happens.
+ */
+export interface TestSharedServices<
+   TAst extends AstNode = AstNode,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TProject extends Project = Project
+> {
+   readonly Clock: Clock;
+   readonly Logger: Logger;
+   readonly Tracer: Tracer;
+   /**
+    * Present only when {@link MakeTestServicesOptions.languages} was passed.
+    * Omitted otherwise so a bundle without declared languages keeps failing
+    * loudly on the slot rather than answering from an empty registry — see
+    * the option's doc for why that default is deliberate.
+    */
+   readonly ServiceRegistry?: StubServiceRegistry;
+   readonly workspace: {
+      LangiumDocuments: StubLangiumDocuments<TAst, TDiagnostic>;
+      DocumentBuilder: StubDocumentBuilder;
+      TextDocuments: StubHydraniumTextDocuments;
+      AstDocumentManager: StubAstDocumentManager<TAst, TDiagnostic>;
+      FileSystemProvider: StubWritableFileSystem;
+      SelfSaveRegistry: StubSelfSaveRegistry;
+      ProjectManager: StubProjectManager<TProject>;
+      DocumentUriPolicy: DocumentUriPolicy;
+      /**
+       * Present only when {@link MakeTestServicesOptions.seedIndex} was passed.
+       * Omitted otherwise for the same reason as `ServiceRegistry` — see that
+       * option's doc.
+       */
+      IndexManager?: StubIndexManager;
+      /**
+       * The REAL `HydraniumWorkspaceLock`, not a stub — it is a few lines of
+       * promise queueing with no I/O, and `ModelService`'s build path serialises
+       * through it, so a no-op stub would hide exactly the interleaving the lock
+       * exists to prevent. The framework subclass rather than Langium's default
+       * because it also marks the write scope that `ModelService`'s reentrancy
+       * guard reads; binding the default here would make the guard untestable
+       * through this tree and let a reentrant write pass unnoticed.
+       */
+      WorkspaceLock: WorkspaceLock;
+   };
+   readonly model: {
+      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+   };
+}
+
+/** Optional configuration for {@link makeTestServices}. */
+export interface MakeTestServicesOptions<
+   TAst extends AstNode = AstNode,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TProject extends Project = Project
+> {
+   /**
+    * Serialiser used by the bundled `StubModelService`. The stub tree
+    * routes no per-language `Serializer` (the stub languages bind no-op slots),
+    * so the framework's own serialize path is unavailable here — supply this
+    * whenever a test asserts on the produced text.
+    *
+    * Default: `JSON.stringify(root)` — deterministic and grammar-free, suitable
+    * for tests that don't assert on the produced text.
+    */
+   serialize?: (uri: string, root: TTransfer) => string;
+   /**
+    * Languages to register on a {@link StubServiceRegistry} bound on the
+    * `ServiceRegistry` slot. This is how a test gets multi-language routing:
+    * production code under test then resolves per-URI through Langium's real
+    * lookup ladder instead of a per-file hand-rolled registry object.
+    *
+    * **Default: no `ServiceRegistry` slot at all.** Binding an empty registry
+    * by default would silently change behaviour for the tests that rely on the
+    * slot being absent — `ModelService.updateRewriteService` optional-chains it
+    * precisely for those bundles — so a registry appears only when a test asks
+    * for one.
+    */
+   languages?: readonly StubLanguageDescriptor[];
+   /**
+    * Documents to declare open with a client-supplied `languageId`, as
+    * `{ [uri]: languageId }`. Forwarded to {@link makeStubServiceRegistry};
+    * only meaningful alongside {@link languages}.
+    */
+   openLanguageIds?: Readonly<Record<string, string>>;
+   /**
+    * Clock bound on the `Clock` shared slot. Pass `makeFakeClock()` to drive
+    * time-gated logic deterministically; defaults to a real {@link SystemClock}.
+    */
+   clock?: Clock;
+   /**
+    * Logger bound on the `Logger` slot AND wrapped by the `Tracer` slot, so a
+    * capturing logger sees both plain log lines and tracer-emitted timing/warn
+    * lines. Defaults to a {@link NoopLogger}.
+    */
+   logger?: Logger;
+   /** Initial documents to seed the {@link StubLangiumDocuments} with. */
+   seedDocuments?: ReadonlyArray<{
+      uri: string;
+      root: TAst;
+      options?: FakeDocumentOptions<TAst, TDiagnostic>;
+   }>;
+   /** Initial projects to seed the {@link StubProjectManager} with. */
+   seedProjects?: readonly TProject[];
+   /**
+    * Global-index entries to seed a {@link StubIndexManager} with, bound on the
+    * `IndexManager` slot. This is how a test reaches the global scope —
+    * `DefaultScopeProvider` reads that slot — so a scope assertion can
+    * distinguish "closed" from "falls through to the index".
+    *
+    * **Default: no `IndexManager` slot at all**, matching {@link languages}.
+    * Binding an empty stub by default would answer every global-index read with
+    * an empty result instead of failing on the unbound slot, which is the
+    * silent-`undefined` failure the boundary cast below is annotated for; a
+    * suite that never asks for an index would then pass for a new reason.
+    */
+   seedIndex?: readonly AstNodeDescription[];
+   /**
+    * Policy bound on the `DocumentUriPolicy` slot. Defaults to
+    * {@link DefaultDocumentUriPolicy} (syntactic normalize). Pass a stub that
+    * resolves chosen URIs to a shared canonical form to exercise the
+    * symlink-divergence bridges without touching the filesystem.
+    */
+   documentUriPolicy?: DocumentUriPolicy;
+   /**
+    * Override the {@link ModelService} factory. Use for tests that want a
+    * custom subclass with `normalize` / lifecycle hooks; the default builds
+    * a `StubModelService` from `options.serialize`.
+    */
+   modelService?: (services: ServerSharedServices<TProject>) => ModelService<TAst, TDiagnostic, TTransfer>;
+   /**
+    * Framework {@link ModelServiceOptions} for the DEFAULT stub service, so a
+    * test can reach an option-gated path (`serializeBuilds`, the slow-warn
+    * threshold) without supplying a whole {@link modelService} factory. Ignored
+    * when `modelService` is given — that factory owns its own construction.
+    */
+   modelServiceOptions?: ModelServiceOptions;
+   /**
+    * Override the {@link TransferEncoder} factory. Default: framework
+    * {@link TransferEncoder} with no overrides.
+    */
+   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<unknown, TDiagnostic>;
+}
+
+/**
+ * Bundle returned by {@link makeTestServices}. Exposes the assembled
+ * {@link ServerSharedServices} tree plus every stub the bundle composed,
+ * so tests can introspect or mutate the underlying state without re-wiring
+ * the tree. Each stub member is named after the slot it is bound on.
+ *
+ * This is the core harness and satisfies the uniform {@link Harness}
+ * contract — `services` is the **subject** (the assembled service tree the
+ * production code under test runs against), the individual `*` stubs are the
+ * **seam** (the doubles tests introspect / mutate), and `dispose()` is the
+ * uniform teardown hook (a no-op: the stubs hold only in-memory state,
+ * released with the bundle when it goes out of scope).
+ */
+export interface TestServicesBundle<
+   TAst extends AstNode = AstNode,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TProject extends Project = Project
+> extends Harness {
+   readonly services: ServerSharedServices<TProject>;
+   readonly documents: StubLangiumDocuments<TAst, TDiagnostic>;
+   readonly textDocuments: StubHydraniumTextDocuments;
+   readonly astDocumentManager: StubAstDocumentManager<TAst, TDiagnostic>;
+   readonly documentBuilder: StubDocumentBuilder;
+   readonly fileSystem: StubWritableFileSystem;
+   readonly selfSaveRegistry: StubSelfSaveRegistry;
+   readonly projectManager: StubProjectManager<TProject>;
+   readonly documentUriPolicy: DocumentUriPolicy;
+   /**
+    * The registry bound on the `ServiceRegistry` slot, or `undefined` when no
+    * {@link MakeTestServicesOptions.languages} were declared.
+    */
+   readonly serviceRegistry: StubServiceRegistry | undefined;
+   /**
+    * The stub bound on the `IndexManager` slot, or `undefined` when no
+    * {@link MakeTestServicesOptions.seedIndex} was passed.
+    */
+   readonly indexManager: StubIndexManager | undefined;
+   readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>;
+   readonly transferEncoder: TransferEncoder<unknown, TDiagnostic>;
+   readonly logger: Logger;
+   /** The clock bound on the `Clock` slot — a `makeFakeClock()` if one was passed. */
+   readonly clock: Clock;
+}
+
+/**
+ * Build a {@link ServerSharedServices} tree backed by the framework's
+ * testing stubs. The returned bundle exposes both the tree and the
+ * individual stubs so tests can introspect.
+ *
+ * **Scope.** Langium-layer stubs only — no GLSP-shaped fixtures. Tests for
+ * code that runs against real Langium services (grammar parsing, scope
+ * computation, etc.) should keep using `bootstrapLangium(...)` rather than
+ * this bundle.
+ */
+export function makeTestServices<
+   TAst extends AstNode = AstNode,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TTransfer extends TransferElement = TransferElement,
+   TProject extends Project = Project
+>(
+   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject> = {}
+): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject> {
+   const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
+   const textDocuments = makeStubHydraniumTextDocuments();
+   const documentBuilder = makeStubDocumentBuilder();
+   const selfSaveRegistry = makeStubSelfSaveRegistry();
+   const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
+   const projectManager = makeStubProjectManager<TProject>(options.seedProjects);
+   const astDocumentManager = makeStubAstDocumentManager<TAst, TDiagnostic>(textDocuments, fileSystem, documents);
+   const logger = options.logger ?? new NoopLogger();
+   const clock = options.clock ?? new SystemClock();
+   const tracer = new DefaultTracer(logger, clock);
+   const documentUriPolicy = options.documentUriPolicy ?? new DefaultDocumentUriPolicy();
+   const serviceRegistry = options.languages
+      ? makeStubServiceRegistry(options.languages, { openLanguageIds: options.openLanguageIds })
+      : undefined;
+   const indexManager = options.seedIndex ? makeStubIndexManager(options.seedIndex) : undefined;
+
+   // Build the literal at its honest narrow type (TestSharedServices) so
+   // signature drift on any of these slots produces a compile error here, then
+   // cast at the boundary to ServerSharedServices so production consumers that
+   // expect the full service tree can accept it. The cast is `as unknown as`
+   // because TestSharedServices is structurally narrower (no AstNodeLocator,
+   // IndexManager, WorkspaceManager, …); production code that reads one of
+   // those slots off the bundle fails at runtime.
+   //
+   // **So adding a new service READ to a production path means adding the slot
+   // here too.** Nothing enforces it: the cast below erases the difference, so
+   // the omission surfaces as a runtime `undefined` inside whichever package
+   // happens to drive that path — typically several layers from the change, and
+   // in a package that did not touch the edit. Prefer the REAL service when it
+   // is dependency-free (as `HydraniumWorkspaceLock` is) — a no-op stub of a
+   // synchronisation primitive hides the very interleaving it exists to prevent.
+   //
+   // `model.TransferEncoder` / `model.ModelService` are populated below
+   // (after the factories run); the literal uses unsafe casts to
+   // partially-built objects to satisfy TestSharedServices, then patches
+   // them in.
+   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject> = {
+      Clock: clock,
+      Logger: logger,
+      Tracer: tracer,
+      // Spread rather than assigned so the slot is genuinely ABSENT (not
+      // present-and-undefined) when no languages were declared — `'ServiceRegistry'
+      // in services` is what an optional-chaining production path effectively asks.
+      ...(serviceRegistry ? { ServiceRegistry: serviceRegistry } : {}),
+      workspace: {
+         LangiumDocuments: documents,
+         DocumentBuilder: documentBuilder,
+         TextDocuments: textDocuments,
+         AstDocumentManager: astDocumentManager,
+         FileSystemProvider: fileSystem,
+         SelfSaveRegistry: selfSaveRegistry,
+         ProjectManager: projectManager,
+         DocumentUriPolicy: documentUriPolicy,
+         // Spread for the same reason as `ServiceRegistry` above — the slot must
+         // be genuinely ABSENT, not present-and-undefined, when no index was seeded.
+         ...(indexManager ? { IndexManager: indexManager } : {}),
+         WorkspaceLock: new HydraniumWorkspaceLock()
+      },
+      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject>['model']
+   };
+   const sharedServices = services as unknown as ServerSharedServices<TProject>;
+
+   const serialize = options.serialize ?? ((_uri: string, root: TTransfer) => JSON.stringify(root));
+   const transferEncoder = options.transferEncoder
+      ? options.transferEncoder(sharedServices)
+      : new TransferEncoder<unknown, TDiagnostic>(sharedServices);
+   const modelService = options.modelService
+      ? options.modelService(sharedServices)
+      : makeStubModelService<TAst, TDiagnostic, TTransfer>(sharedServices, serialize, options.modelServiceOptions);
+
+   const mutableModel = services.model as {
+      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+   };
+   mutableModel.TransferEncoder = transferEncoder;
+   mutableModel.ModelService = modelService;
+
+   return {
+      services: sharedServices,
+      documents,
+      textDocuments,
+      astDocumentManager,
+      documentBuilder,
+      fileSystem,
+      selfSaveRegistry,
+      projectManager,
+      documentUriPolicy,
+      serviceRegistry,
+      indexManager,
+      modelService,
+      transferEncoder,
+      logger,
+      clock,
+      dispose: () => {
+         // No-op: the bundled stubs hold only in-memory state (maps, arrays),
+         // released with the bundle when it goes out of scope. The hook exists
+         // to satisfy the uniform Harness contract so teardown is always
+         // `harness.dispose()` regardless of which harness.
+      }
+   };
+}

package/src/testing/make-test-tracer.ts

@@ -0,0 +1,92 @@
+/********************************************************************************
+ * 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 Clock, DefaultTracer, type Logger, type LogLevel, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
+
+/**
+ * No-op {@link Tracer} for tests — discards all output with real fluent
+ * behaviour. Use to fill the `Tracer` slot of a hand-rolled fake services tree
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new DefaultTracer()` (which already defaults to a {@link NoopLogger} +
+ * {@link SystemClock}); the named helper reads better at call sites and gives a
+ * single place to evolve the test tracer.
+ */
+export function makeNoopTracer(): Tracer {
+   return new DefaultTracer();
+}
+
+/**
+ * No-op {@link Logger} for tests — discards all output with real fluent
+ * behaviour (`for`/`sub`/`with` derive no-op children; `withUri`
+ * short-circuits to the same instance). Use to fill
+ * a `Logger` slot, or to satisfy a service/function that takes a bare `Logger`,
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new NoopLogger()`; the named helper is the bare-logger sibling of
+ * {@link makeNoopTracer} and gives a single place to evolve the test logger.
+ * Prefer this over hand-rolling a `{ for, sub, with, trace } as unknown as
+ * Logger` stub — those omit methods and drift from the real surface.
+ */
+export function makeNoopLogger(): Logger {
+   return new NoopLogger();
+}
+
+/** A captured emission: log level + rendered message. */
+export interface CapturedLine {
+   readonly level: LogLevel;
+   readonly message: string;
+}
+
+/** A {@link Logger} whose emitted lines are captured for assertions. */
+export interface CapturingLogger {
+   readonly logger: Logger;
+   /** Every line emitted through the logger (and its derived children), in order. */
+   readonly lines: CapturedLine[];
+}
+
+/**
+ * Capturing {@link Logger} for tests that assert on emitted output. Backed by a
+ * complete {@link NoopLogger} subclass — so every emit method and `for`/`sub`/
+ * `with`/`withUri` derivation works fluently — that records each emitted line
+ * into {@link CapturingLogger.lines}. Derived child loggers share the same sink.
+ * Emission is still threshold-gated, so set the level (`Logger.setLevel(...)`)
+ * to the tier under test — `'trace'` captures everything. Prefer this over
+ * hand-rolling a capturing `{ info, warn, ... } as unknown as Logger` stub.
+ */
+export function makeCapturingLogger(): CapturingLogger {
+   const lines: CapturedLine[] = [];
+   class Capturing extends NoopLogger {
+      protected override emit(level: LogLevel, _label: string, message: string): void {
+         lines.push({ level, message });
+      }
+      protected override derive(component: string): this {
+         return new Capturing(component) as this;
+      }
+   }
+   return { logger: new Capturing(), lines };
+}
+
+/** A {@link Tracer} whose emitted lines are captured for assertions. */
+export interface CapturingTracer {
+   readonly tracer: Tracer;
+   /** Every line emitted through the tracer (and its derived children), in order. */
+   readonly lines: CapturedLine[];
+}
+
+/**
+ * Capturing {@link Tracer} for tests that assert on emitted output. Wraps a
+ * {@link makeCapturingLogger} in a {@link DefaultTracer} so timing/profiling
+ * lines are captured alongside plain log lines. Emission is threshold-gated, so
+ * set the level (`Logger.setLevel(...)`) to the tier under test. Pass a
+ * {@link Clock} to share the test's fake-time axis; defaults to
+ * {@link SystemClock}.
+ */
+export function makeCapturingTracer(clock: Clock = new SystemClock()): CapturingTracer {
+   const { logger, lines } = makeCapturingLogger();
+   return { tracer: new DefaultTracer(logger, clock), lines };
+}

package/src/testing/node/generated-workspace.ts

@@ -0,0 +1,222 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Scaffolding for a generated on-disk corpus: the seeded PRNG, the
+ * overwrite permit, the newline normalisation and the per-extension tally.
+ * The caller supplies only the content.
+ *
+ * # Why the corpus is generated rather than committed
+ *
+ * A volume fixture is what a profiling run, a `watch` claim and any
+ * incremental-rebuild claim measure against, and it is several hundred files.
+ * Committing a deterministic generator and gitignoring its output keeps the
+ * artefact reproducible by any contributor at a fixed seed without the
+ * repository carrying the files.
+ *
+ * # Determinism is the whole contract, and it is fragile
+ *
+ * A performance figure is only readable beside another figure taken over the
+ * same input, so "same parameters, same bytes" is not a nicety. Three things
+ * break it and all three are handled here rather than left to each generator:
+ * `Math.random` (hence {@link GeneratedWorkspaceWriter.random}, a seeded
+ * mulberry32), a timestamp anywhere in the output (hence nothing written here
+ * records one), and platform line endings (hence
+ * {@link GeneratedWorkspaceWriter.write} normalising to LF).
+ *
+ * The draw order is the caller's responsibility, and it is the one that catches
+ * people out: the PRNG is a single stream, so a generator that reorders its
+ * emission — or draws conditionally on something it did not draw before —
+ * produces a different corpus at the same seed.
+ *
+ * # Size is a parameter because the signal is a CURVE
+ *
+ * An O(n²) regression in discovery, indexing, scope or linking is invisible in
+ * a single measurement: it shows up as the large/small ratio outrunning the
+ * file-count ratio. That is why this is a callable module rather than only a
+ * script — a bench runs it in-process at two sizes instead of shelling out —
+ * and why a generator built on it should take its sizes as options rather than
+ * fixing one N.
+ *
+ * # The marker is a permit, not a label
+ *
+ * Generating wipes the target directory, the caller names that directory, and
+ * the default is typically inside the repository. So the wipe needs
+ * authorisation: an absent directory, an empty one, or one already carrying the
+ * marker file. Anything else throws rather than deleting a tree this generator
+ * did not write.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+
+/** Default name of the file that records — and authorises — a generated corpus. */
+export const GENERATED_WORKSPACE_MARKER = '.hydranium-generated-workspace';
+
+/** The write surface {@link makeGeneratedWorkspace} hands to {@link GeneratedWorkspaceOptions.emit}. */
+export interface GeneratedWorkspaceWriter {
+   /** Absolute, resolved path of the corpus root. Already created and empty. */
+   readonly root: string;
+   /**
+    * Next value of the seeded stream, in `[0, 1)`.
+    *
+    * One stream for the whole corpus, drawn in emission order — so this is
+    * reproducible only as long as the emission order is. Prefer drawing
+    * unconditionally over drawing inside a branch.
+    */
+   random(): number;
+   /** An integer in `[minimum, maximum]`, both inclusive, off the same stream. */
+   randomInt(minimum: number, maximum: number): number;
+   /**
+    * Write `content` at `relativePath` under {@link root}, creating parent
+    * directories, and count it in the summary's tally. Returns the absolute
+    * path.
+    *
+    * Line endings are normalised to LF, without which the corpus is not
+    * byte-identical across platforms and the determinism contract holds only on
+    * one OS.
+    */
+   write(relativePath: string, content: string): string;
+   /** Create a directory under {@link root} and return its absolute path. */
+   directory(relativePath: string): string;
+}
+
+/** Inputs to {@link makeGeneratedWorkspace}. */
+export interface GeneratedWorkspaceOptions {
+   /** Directory to write into. Created if absent; wiped if the marker permits it. */
+   readonly root: string;
+   /**
+    * Identifies the generator in the marker file, so a corpus found on disk
+    * says what produced it. Free-form; a package-qualified name reads best.
+    */
+   readonly generator: string;
+   /**
+    * Recorded in the marker alongside the seed — the sizes the corpus was
+    * generated at, which is what makes a measurement taken over it
+    * interpretable later.
+    */
+   readonly parameters?: Readonly<Record<string, number | string | boolean>>;
+   /** Seed for the content stream. Defaults to `0`; the same seed reproduces the corpus byte for byte. */
+   readonly seed?: number;
+   /** Marker file name. Defaults to {@link GENERATED_WORKSPACE_MARKER}. */
+   readonly marker?: string;
+   /** Emit the content. Called once, after the root is prepared and the marker written. */
+   emit(writer: GeneratedWorkspaceWriter): void;
+}
+
+/** What {@link makeGeneratedWorkspace} wrote. */
+export interface GeneratedWorkspaceSummary {
+   /** Absolute, resolved corpus root. */
+   readonly root: string;
+   /** Seed actually used, after the default. */
+   readonly seed: number;
+   /** Marker file name actually used, relative to {@link root}. */
+   readonly marker: string;
+   /**
+    * How many files `emit` wrote, keyed by extension WITH the leading dot
+    * (`'.domain'`). The marker is not counted; everything `emit` wrote is,
+    * including any README, so a caller wanting a model-file subtotal adds up
+    * the extensions it considers model files.
+    *
+    * A tally is worth returning rather than leaving to the caller because it is
+    * the cheap assertion that catches the expensive defect: a generator whose
+    * nested loops skip a file still reports the size it was asked for, and the
+    * corpus is then quietly smaller than the number a measurement is filed
+    * under. Read it against a count taken off the filesystem, not instead of
+    * one — this counts the calls, so it cannot see a failed write.
+    */
+   readonly files: Readonly<Record<string, number>>;
+   /** Total files `emit` wrote, the marker excluded. */
+   readonly total: number;
+}
+
+/**
+ * A deterministic 32-bit PRNG (mulberry32). Deliberately not `Math.random`: a
+ * corpus that varies per run cannot carry a comparable measurement.
+ */
+function makeRandom(seed: number): () => number {
+   let state = seed >>> 0;
+   return () => {
+      state = (state + 0x6d2b79f5) >>> 0;
+      let mixed = state;
+      mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+      mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+      return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+   };
+}
+
+/**
+ * Prepare `root` for a fresh corpus, or throw naming the marker that would
+ * have authorised the wipe.
+ */
+function prepareRoot(root: string, marker: string): void {
+   if (existsSync(root)) {
+      const entries = readdirSync(root);
+      if (entries.length > 0 && !entries.includes(marker)) {
+         throw new Error(
+            `Refusing to overwrite ${root}: it is not empty and carries no ${marker} marker. ` +
+               'Point the output at a fresh directory, or delete this one yourself.'
+         );
+      }
+      rmSync(root, { recursive: true, force: true });
+   }
+   mkdirSync(root, { recursive: true });
+}
+
+/**
+ * Generate a corpus under `options.root` and return what was written.
+ *
+ * The marker is written BEFORE `emit` runs, so an emission that throws
+ * half-way leaves a directory the next run is still permitted to wipe. Writing
+ * it afterwards would strand a partial corpus that has to be deleted by hand,
+ * and it buys nothing: the marker only ever lands in a directory this function
+ * has just created or been authorised to clear.
+ */
+export function makeGeneratedWorkspace(options: GeneratedWorkspaceOptions): GeneratedWorkspaceSummary {
+   const root = path.resolve(options.root);
+   const marker = options.marker ?? GENERATED_WORKSPACE_MARKER;
+   const seed = options.seed ?? 0;
+   if (!Number.isInteger(seed)) {
+      throw new Error(`seed must be an integer, got ${String(seed)}`);
+   }
+   prepareRoot(root, marker);
+
+   const random = makeRandom(seed);
+   const files: Record<string, number> = {};
+   let total = 0;
+   const writeFile = (target: string, content: string): void => {
+      mkdirSync(path.dirname(target), { recursive: true });
+      writeFileSync(target, content.replace(/\r\n/g, '\n'), 'utf8');
+   };
+
+   // Nothing here records a timestamp, which is the other half of the
+   // byte-reproducibility property the seeded stream gives.
+   writeFile(path.join(root, marker), `${JSON.stringify({ generator: options.generator, seed, ...options.parameters }, undefined, 2)}\n`);
+
+   options.emit({
+      root,
+      random,
+      randomInt: (minimum, maximum) => minimum + Math.floor(random() * (maximum - minimum + 1)),
+      write(relativePath, content) {
+         const target = path.join(root, relativePath);
+         writeFile(target, content);
+         const extension = path.extname(relativePath);
+         files[extension] = (files[extension] ?? 0) + 1;
+         total += 1;
+         return target;
+      },
+      directory(relativePath) {
+         const target = path.join(root, relativePath);
+         mkdirSync(target, { recursive: true });
+         return target;
+      }
+   });
+
+   return { root, seed, marker, files, total };
+}