@hydranium/conformance 1.0.0-next.10

package/src/conformance-suite.ts

@@ -0,0 +1,148 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * One conformance check. A check with a {@link body} is RUN (emitted as a
+ * runner test); a check WITHOUT a body is SKIPPED — its optional fixture input
+ * was absent, so it reports as skipped with a named {@link skipReason} rather
+ * than passing vacuously. The false-green guard (require both a valid and an
+ * invalid model) lives in the slices; this type is the head-agnostic unit they
+ * build.
+ */
+export interface ConformanceCheck {
+   readonly title: string;
+   /** Present ⇒ the check runs. Absent ⇒ the check is skipped with {@link skipReason}. */
+   readonly body?: () => void | Promise<void>;
+   /** Why the check was skipped — surfaced in the `it.skip` title and the summary. */
+   readonly skipReason?: string;
+}
+
+/** A single skipped check in a {@link ConformanceSummary}. */
+export interface SkippedCheck {
+   readonly title: string;
+   readonly reason: string;
+}
+
+/** Ran-vs-skipped tally over a battery of {@link ConformanceCheck}s. */
+export interface ConformanceSummary {
+   readonly total: number;
+   readonly ran: number;
+   readonly skipped: ReadonlyArray<SkippedCheck>;
+}
+
+/** Placeholder reason for a skipped check that supplied none. */
+const NO_REASON = 'no reason given';
+
+/**
+ * Tally a battery of checks into ran-vs-skipped counts. A check is RAN when
+ * it carries a {@link ConformanceCheck.body}; otherwise it is SKIPPED and its
+ * (possibly defaulted) reason is collected.
+ */
+export function summarizeChecks(checks: ReadonlyArray<ConformanceCheck>): ConformanceSummary {
+   const skipped: SkippedCheck[] = [];
+   let ran = 0;
+   for (const check of checks) {
+      if (check.body) {
+         ran++;
+      } else {
+         skipped.push({ title: check.title, reason: check.skipReason ?? NO_REASON });
+      }
+   }
+   return { total: checks.length, ran, skipped };
+}
+
+/**
+ * The `it.skip` title for a skipped check — the check title annotated with
+ * its (possibly defaulted) reason, so the runner's report explains the skip
+ * inline instead of showing a bare greyed-out line.
+ */
+export function skippedTitle(check: Pick<ConformanceCheck, 'title' | 'skipReason'>): string {
+   return `${check.title} [skipped: ${check.skipReason ?? NO_REASON}]`;
+}
+
+/**
+ * Render a one-or-more-line human summary of a {@link ConformanceSummary},
+ * prefixed by the suite name. Printed once per suite so a half-implemented
+ * adopter reads as *skipped*, never as a silent false green.
+ */
+export function formatSummary(suite: string, summary: ConformanceSummary): string {
+   const header = `${suite}: ${summary.ran}/${summary.total} ran, ${summary.skipped.length} skipped`;
+   if (summary.skipped.length === 0) {
+      return header;
+   }
+   const lines = summary.skipped.map(skip => `  - skipped: ${skip.title} (${skip.reason})`);
+   return [header, ...lines].join('\n');
+}
+
+/**
+ * Write the ran-vs-skipped summary somewhere a test runner does not swallow.
+ *
+ * `console.log` is NOT that place: vitest attributes console output to the
+ * running task, and an `afterAll` hook has none, so the line is dropped with no
+ * warning — measured, not inferred. That silently disables the kit's only
+ * false-green guard: a half-implemented adopter is supposed to read as
+ * *skipped*, and with the summary gone it reads as a clean pass.
+ *
+ * `process.stderr` bypasses the interception. A runner with no `process` (a
+ * browser runner) falls back to `console.log`, where nothing is intercepting in
+ * the first place — the kit's `.` entry is neutrality-gated, so this must not
+ * assume Node.
+ */
+export function writeConformanceSummary(text: string): void {
+   const stderr = (globalThis as { process?: { stderr?: { write?(chunk: string): unknown } } }).process?.stderr;
+   if (typeof stderr?.write === 'function') {
+      stderr.write(`${text}\n`);
+      return;
+   }
+   console.log(text);
+}
+
+/**
+ * The minimal test-runner surface {@link emitConformanceSuite} drives, so the
+ * kit core names NO concrete runner (`@jest/globals` / `vitest` / `node:test`)
+ * and stays runner-agnostic. A thin per-runner adapter subpath
+ * (`@hydranium/conformance/jest`, `@hydranium/conformance/vitest`) binds these
+ * methods to its runner's `describe` / `it` / `it.skip` / `afterAll`.
+ * Structural by design — jest and vitest both satisfy it directly.
+ */
+export interface ConformanceRunner {
+   /** Group the suite's checks under `name`; `register` queues them (called synchronously). */
+   describe(name: string, register: () => void): void;
+   /** Register a running check. */
+   test(name: string, body: () => void | Promise<void>): void;
+   /** Register a skipped check (greyed out, never executed). */
+   skip(name: string): void;
+   /** Register a once-per-suite teardown — used to print the ran-vs-skipped summary. */
+   afterAll(fn: () => void | Promise<void>): void;
+}
+
+/**
+ * Emit a battery of {@link ConformanceCheck}s through an injected
+ * {@link ConformanceRunner} — each check with a body becomes a `test`, each
+ * without becomes a `skip` carrying its {@link skippedTitle}, and an `afterAll`
+ * prints the {@link formatSummary} so the suite always reports ran-vs-skipped.
+ * The thin, runner-agnostic translation layer between a slice's planned checks
+ * (whose ran/skip decisions are the tested pure logic above) and a runner; a
+ * per-runner adapter's `runXxxConformance` builds the check list and hands it
+ * here with the runner bound.
+ */
+export function emitConformanceSuite(runner: ConformanceRunner, suite: string, checks: ReadonlyArray<ConformanceCheck>): void {
+   runner.describe(suite, () => {
+      for (const check of checks) {
+         if (check.body) {
+            runner.test(check.title, check.body);
+         } else {
+            runner.skip(skippedTitle(check));
+         }
+      }
+      runner.afterAll(() => {
+         writeConformanceSummary(formatSummary(suite, summarizeChecks(checks)));
+      });
+   });
+}

package/src/data/index.ts

@@ -0,0 +1,297 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The `@hydranium/conformance/data` slice — protocol conformance for the
+ * data-server head. The driver port IS the protocol-native
+ * {@link DataServerProtocol} proxy (plus the captured `onDocumentUpdated`
+ * events), so no upstream wire-lib dep enters the kit and `DataServerHarness`
+ * satisfies the port structurally with no adapter.
+ */
+
+import assert from 'node:assert/strict';
+import { TransferDocument, type TransferDiagnostic, type TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
+import { type Harness, waitFor } from '@hydranium/protocol/testing';
+import type { ConformanceCheck } from '../conformance-suite.js';
+import { type LanguageFixture, resolveDeferred, resolveModel } from '../model.js';
+
+/**
+ * The data-server driver port — a live, connected, READY data-server exposed
+ * through its protocol-native proxy plus the captured client-side update
+ * events. The kit names only `@hydranium/protocol` types, so a
+ * `DataServerHarness` satisfies the port structurally (it has `proxy` +
+ * `events` + `dispose`) with NO adapter. `extends Harness` gives the kit the
+ * universal `dispose()` teardown.
+ *
+ * The kit seeds documents purely through the proxy: `updateModelDocument` is
+ * an upsert (it creates a cold URI from the payload, not just modifies an
+ * existing one), so the slice needs no services-level open hook. The adopter
+ * only has to stand the server up READY in its `connect` — see
+ * {@link DataConformanceOptions.connect}.
+ */
+export interface DataConformanceDriver<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> extends Harness {
+   readonly proxy: DataServerProtocol<TTransfer, TDiagnostic>;
+   /** Captured `onDocumentUpdated` events, append order — the subscription check's observation target. */
+   readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+}
+
+/** Options for `runDataConformance`. */
+export interface DataConformanceOptions<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   /**
+    * Establish a freshly-wired, connected, READY data-server driver. Called
+    * once per check for isolation; the kit disposes it after the check. The
+    * adopter must initialise the workspace before returning, so `waitForReady`
+    * resolves rather than hanging.
+    */
+   readonly connect: () => DataConformanceDriver<TTransfer, TDiagnostic> | Promise<DataConformanceDriver<TTransfer, TDiagnostic>>;
+   /** Per-language fixtures; the grammar-bearing checks run once per language. */
+   readonly languages: ReadonlyArray<LanguageFixture>;
+   /**
+    * Set this when the head under test HAS a project tier. Supplying it IS the
+    * claim that `getProjects` answers at least one project, so an empty array
+    * becomes a failure rather than a vacuous pass.
+    *
+    * Left unset the claim is not made and the check reports skipped with a
+    * named reason, because `[]` is the documented answer for a head with no
+    * project tier (`UNQUALIFIED_PROJECT_REFERENCE` everywhere) — indistinguishable
+    * from "never implemented" without the adopter saying which it is.
+    */
+   readonly expectsProjects?: boolean;
+   /** Suite title override. Default `'conformance: data-server'`. */
+   readonly suiteTitle?: string;
+}
+
+/** Client id the kit seeds/edits documents under (the originating author). */
+const AUTHOR = 'conformance-author';
+/** Client id the kit subscribes under — distinct from {@link AUTHOR} so the echo is recognisable. */
+const SUBSCRIBER = 'conformance-subscriber';
+/**
+ * Client id for a write made BEFORE any subscription exists. Distinct from
+ * {@link AUTHOR} so an event caused by it is recognisable: a head that fans
+ * notifications out regardless of its subscription table is otherwise
+ * indistinguishable from one that honours the table, since both deliver
+ * something for the post-subscribe write.
+ */
+const SEEDER = 'conformance-seeder';
+
+/**
+ * Build the data-server check battery: server-level checks once, then the
+ * grammar-bearing checks per language. Each check connects a fresh driver
+ * and disposes it, so checks never interfere. Exported for the kit's own
+ * unit tests; adopters call `runDataConformance`.
+ *
+ * `LanguageFixture.edit` is read HERE and nowhere else in the kit, and is
+ * optional: its two checks report skipped when it is absent. See
+ * {@link LanguageFixture} for which slice reads which field.
+ */
+export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic>(
+   options: DataConformanceOptions<TTransfer, TDiagnostic>
+): ConformanceCheck[] {
+   const { connect, expectsProjects } = options;
+   const checks: ConformanceCheck[] = [];
+
+   // Split from `waitForReady` so a failure names which of the two broke.
+   //
+   // SHAPE ONLY: an empty array is the documented answer for a head with no
+   // project tier, so "returns `[]`" passes here and is indistinguishable from
+   // "never implemented". The discriminating part is the element-type assertion
+   // (it fails a head answering with the wrong element type, which the bare
+   // `Array.isArray` it replaced could not) plus the separate emptiness check
+   // below, which only an adopter's `expectsProjects` can license.
+   checks.push({
+      title: 'getProjects answers an array of well-formed projects',
+      body: async () => {
+         const driver = await connect();
+         try {
+            const projects = await driver.proxy.getProjects();
+            assert.ok(Array.isArray(projects), 'getProjects did not return an array');
+            for (const project of projects) {
+               assert.ok(
+                  typeof project?.id === 'string' && project.id.length > 0,
+                  `getProjects returned a project with no id: ${JSON.stringify(project)}`
+               );
+               // Type, not emptiness: the empty string is
+               // `UNQUALIFIED_PROJECT_REFERENCE`, the documented value for a
+               // project that does not qualify names, and the framework's own
+               // reference example uses it. Requiring non-empty here failed
+               // that example and would have failed every adopter taking the
+               // documented default.
+               assert.ok(typeof project.referenceName === 'string', `project ${project.id} has no referenceName`);
+            }
+            const ids = projects.map(project => project.id);
+            assert.strictEqual(new Set(ids).size, ids.length, `getProjects returned duplicate project ids: ${ids.join(', ')}`);
+         } finally {
+            driver.dispose();
+         }
+      }
+   });
+
+   // Separate from the shape check so a failure names which claim broke, and
+   // gated because only the adopter knows whether their head has a project
+   // tier at all. Planned either way — reported as skipped with a reason
+   // rather than silently absent, which is what distinguishes an opt-out from
+   // lost coverage.
+   checks.push({
+      title: 'getProjects answers at least one project (projects expected)',
+      skipReason: expectsProjects
+         ? undefined
+         : 'options supplied no `expectsProjects` (an empty project list is the documented answer for a head with no project tier)',
+      body: expectsProjects
+         ? async () => {
+              const driver = await connect();
+              try {
+                 const projects = await driver.proxy.getProjects();
+                 assert.ok(
+                    projects.length > 0,
+                    'getProjects returned an empty array although `expectsProjects` claims the head has a project tier'
+                 );
+              } finally {
+                 driver.dispose();
+              }
+           }
+         : undefined
+   });
+
+   checks.push({
+      title: 'waitForReady resolves rather than hanging or rejecting',
+      body: async () => {
+         const driver = await connect();
+         try {
+            // Resolves `Promise<void>`, and over JSON-RPC a void response comes
+            // back as `null` — so the value carries no information and only the
+            // fact that it settles at all is assertable here.
+            await driver.proxy.waitForReady();
+         } finally {
+            driver.dispose();
+         }
+      }
+   });
+
+   for (const language of options.languages) {
+      const { valid, invalid, edit } = language;
+      const tag = `[${valid.languageId}]`;
+
+      checks.push({
+         title: `getModelDocument(valid) returns a coherent envelope ${tag}`,
+         body: async () => {
+            const driver = await connect();
+            try {
+               // Resolved AFTER `connect`, which is the whole point of allowing a
+               // thunk: the fixture may name a workspace `connect` just created.
+               const model = resolveModel(valid);
+               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text });
+               // `includeDiagnostics` for the same reason the invalid check
+               // passes it: a synchronous read settles at the integrity-settled
+               // phase, so an empty array without it can mean "validation has
+               // not run" rather than "the document is clean".
+               const document = await driver.proxy.getModelDocument({ uri: model.uri, includeDiagnostics: true });
+               assert.strictEqual(document.uri, model.uri);
+               // The SHAPE, not truthiness: `{}` is truthy, so a head answering
+               // a shaped-but-contentless envelope for a document it did parse
+               // would pass. `$type` is the one field every TransferElement
+               // carries, so it is assertable with no fixture knowledge.
+               const { root } = TransferDocument.assertLoaded(document);
+               assert.ok(
+                  typeof root.$type === 'string' && root.$type.length > 0,
+                  `getModelDocument(valid) returned a root with no $type: ${JSON.stringify(root)}`
+               );
+               // `version` is the conflict token every later update gates on, so
+               // an envelope that omits it is unusable however good the root is.
+               assert.ok(
+                  Number.isInteger(document.version),
+                  `getModelDocument(valid) returned a non-integer version: ${String(document.version)}`
+               );
+               assert.deepStrictEqual(document.diagnostics, []);
+            } finally {
+               driver.dispose();
+            }
+         }
+      });
+
+      checks.push({
+         title: `getModelDocument(invalid) reports at least one diagnostic ${tag}`,
+         body: async () => {
+            const driver = await connect();
+            try {
+               const model = resolveModel(invalid);
+               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text });
+               // Diagnostics are a validation-phase product; a synchronous read settles at the
+               // integrity-settled phase by default, so request validation explicitly here.
+               // Safe despite `includeDiagnostics` waiting rather than forcing a build: the
+               // update above has already driven this document through validation.
+               const document = await driver.proxy.getModelDocument({ uri: model.uri, includeDiagnostics: true });
+               assert.ok(document.diagnostics.length >= 1, 'getModelDocument(invalid) reported no diagnostics');
+            } finally {
+               driver.dispose();
+            }
+         }
+      });
+
+      // Opt-in: both remaining checks need a second, observably different model
+      // text, which only `edit` supplies.
+      const editSkipReason = 'fixture supplies no `edit` (data-slice only; omit it if this language is not driven through the data head)';
+
+      checks.push({
+         title: `updateModelDocument applies an edit a follow-up get reflects ${tag}`,
+         skipReason: edit ? undefined : editSkipReason,
+         body: edit
+            ? async () => {
+                 const driver = await connect();
+                 try {
+                    const model = resolveModel(valid);
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text });
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: resolveDeferred(edit.to) });
+                    const document = await driver.proxy.getModelDocument({ uri: model.uri });
+                    assert.ok(edit.expect(document.root), 'edit.expect(root) was false — the edit was not reflected by a follow-up get');
+                 } finally {
+                    driver.dispose();
+                 }
+              }
+            : undefined
+      });
+
+      checks.push({
+         title: `subscribe + update delivers an onDocumentUpdated event with the originating clientId ${tag}`,
+         skipReason: edit ? undefined : editSkipReason,
+         body: edit
+            ? async () => {
+                 const driver = await connect();
+                 try {
+                    const model = resolveModel(valid);
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: SEEDER, model: model.text });
+                    await driver.proxy.watchModelDocument({ uri: model.uri, clientId: SUBSCRIBER });
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: resolveDeferred(edit.to) });
+                    await waitFor(() => driver.events.some(event => event.sourceClientId === AUTHOR), {
+                       message: `no onDocumentUpdated event for ${model.uri} after the post-subscription update`
+                    });
+                    const last = driver.events[driver.events.length - 1];
+                    assert.strictEqual(last.document.uri, model.uri);
+                    assert.strictEqual(last.sourceClientId, AUTHOR);
+                    // Nothing from before the subscription. Waiting for the
+                    // post-subscribe event first is what makes this provable: the
+                    // two notifications share one ordered connection, so a seeding
+                    // event that was ever going to arrive has arrived by now.
+                    assert.ok(
+                       !driver.events.some(event => event.sourceClientId === SEEDER),
+                       'an onDocumentUpdated event arrived for the update made BEFORE watchModelDocument'
+                    );
+                 } finally {
+                    driver.dispose();
+                 }
+              }
+            : undefined
+      });
+   }
+
+   return checks;
+}

package/src/glsp/index.ts

@@ -0,0 +1,217 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The `@hydranium/conformance/glsp` slice — protocol conformance for the GLSP
+ * head, generic over the adopter's action type `TAction`. The kit imports NO
+ * `@eclipse-glsp/*` types: the FIXTURE supplies the native actions
+ * (`requestModel()`, `createOperation.action()`) and the kit matches responses
+ * by `kind` (a `string`) via the driver's `nextAction`.
+ *
+ * The driver port (`GlspConformanceDriver<TAction>`) is the minimal
+ * `start` / `dispatch` / `nextAction` surface that `@hydranium/glsp-server/
+ * testing`'s `GlspHarness` satisfies with no adapter. Grammar-specific setup
+ * and assertions (seeding a source root for the light path, reading the
+ * mutated source model) are the adopter's via `prepare` / `expectResponse` /
+ * `createOperation.expectMutated`, which receive the CONCRETE driver `TDriver`
+ * — so the port stays grammar-agnostic while the adopter keeps full access to
+ * its harness.
+ */
+
+import assert from 'node:assert/strict';
+import type { Harness } from '@hydranium/protocol/testing';
+import type { ConformanceCheck } from '../conformance-suite.js';
+
+/**
+ * The GLSP driver port — a live GLSP server driven through the action
+ * round-trip. Generic over the adopter action type `TAction` so the kit names
+ * no `@eclipse-glsp/*` type. `@hydranium/glsp-server/testing`'s `GlspHarness`
+ * satisfies it structurally with `TAction = Action`. `extends Harness` gives
+ * the kit the universal `dispose()` teardown.
+ */
+export interface GlspConformanceDriver<TAction> extends Harness {
+   /** Drive `initialize` + `initializeClientSession`; resolve once the session exists. */
+   start(): Promise<void>;
+   /** Send an action to the server. Fire-and-forget (GLSP `process` is `void`). */
+   dispatch(action: TAction): void;
+   /** Resolve with the next captured action whose `kind` matches; reject on timeout. */
+   nextAction<T extends TAction = TAction>(kind: string, timeoutMs?: number): Promise<T>;
+}
+
+/**
+ * Opt-in create-operation spec. The adopter supplies the operation action, the
+ * expected response kind it settles with, and a matcher reading the mutated
+ * source model off the concrete driver.
+ */
+export interface GlspCreateOperationSpec<TAction, TDriver extends GlspConformanceDriver<TAction>> {
+   /**
+    * Construct the create operation to dispatch.
+    *
+    * Receives the driver, and is called AFTER the initial `requestModel` has
+    * settled — so the loaded model is available here. Two things depend on that:
+    *
+    * - **Capturing a "before" snapshot.** {@link expectMutated} gets no
+    *   pre-operation state, so an adopter that wants a delta rather than an
+    *   absolute count records it here, in its own closure.
+    * - **Operations that need real element ids.** A `CreateEdgeOperation` names
+    *   a source and target from the index, which do not exist until the model is
+    *   loaded.
+    */
+   readonly action: (driver: TDriver) => TAction;
+   /** The action kind the server settles the operation with (e.g. a re-`RequestBounds` for client-laid-out diagrams). */
+   readonly expectedResponseKind: string;
+   /**
+    * Returns whether the source model gained the element — the adopter reads its
+    * concrete state off `driver`.
+    *
+    * **Receives no pre-operation snapshot of its own**, because the kit owns no
+    * source-model type and cannot capture one generically. An adopter wanting a
+    * delta rather than an absolute count records the before-state in
+    * {@link GlspCreateOperationSpec.action}, which does get the driver and does
+    * run after the model has loaded.
+    *
+    * Sticking to an absolute count is fine too, with one caveat: it couples the
+    * fixture to its input document, so a fixture whose input was MUTATED by an
+    * earlier check silently expects the wrong number. Give each check pristine
+    * input, or take the delta route above.
+    */
+   readonly expectMutated: (driver: TDriver) => boolean;
+}
+
+/**
+ * Per-diagram-type GLSP fixture, generic over the adopter action type and the
+ * concrete driver. The `prepare` hook covers both fidelities: LIGHT seeds a
+ * source root directly (`driver.seedSourceRoot(...)`); FAITHFUL no-ops and lets
+ * the `requestModel` action carry a source URI a real storage loads.
+ */
+export interface GlspFixture<TAction, TDriver extends GlspConformanceDriver<TAction>> {
+   /**
+    * **Title only** — the label every check for this fixture is tagged with.
+    *
+    * It is NOT the diagram type the server runs: `connect` supplies that to the
+    * harness. Appending a fidelity or document suffix here is what makes two
+    * fixtures over ONE diagram type read apart in the report. Nothing validates
+    * this string, so treat it as free-form and make it descriptive; a value that
+    * is only ever displayed is checked by nothing.
+    */
+   readonly diagramType: string;
+   /** Seed (light) or no-op (faithful) after `start`, before the first `requestModel` dispatch. */
+   readonly prepare: (driver: TDriver) => void | Promise<void>;
+   /**
+    * Construct the `RequestModel` action (light: bare; faithful: carrying a
+    * source URI).
+    *
+    * A THUNK, called per check and always AFTER `connect` — so a faithful fixture
+    * may read a root that `connect` just created, which is how an adopter gives
+    * every check pristine on-disk input. The `/data` and `/lsp` slices get the
+    * same per-check resolution from `ConformanceModel`'s deferrable fields.
+    */
+   readonly requestModel: () => TAction;
+   /** The action kind the server responds to `requestModel` with (e.g. `RequestBoundsAction.KIND`). */
+   readonly expectedResponseKind: string;
+   /** Optional matcher over the response action — the adopter digs into the projected GModel (the kit owns no GModel types). */
+   readonly expectResponse?: (response: TAction) => boolean;
+   /** Opt-in: a create operation that must mutate the source model. */
+   readonly createOperation?: GlspCreateOperationSpec<TAction, TDriver>;
+}
+
+/** Options for `runGlspConformance`. */
+export interface GlspConformanceOptions<TAction, TDriver extends GlspConformanceDriver<TAction>> {
+   /**
+    * Establish a freshly-wired GLSP driver (NOT started — the kit drives
+    * `start()` per check). Called once per check for isolation; the kit
+    * disposes it. The faithful path must build the workspace here first, so
+    * storage has something to load.
+    */
+   readonly connect: () => TDriver | Promise<TDriver>;
+   /** Per-diagram-type fixtures. */
+   readonly diagrams: ReadonlyArray<GlspFixture<TAction, TDriver>>;
+   /** Suite title override. Default `'conformance: glsp'`. */
+   readonly suiteTitle?: string;
+}
+
+/**
+ * Build the GLSP check battery — per diagram type: `start()` resolves;
+ * `RequestModel` responds with the expected kind (+ optional `expectResponse`
+ * matcher); and an OPT-IN create-operation check (absent ⇒ `it.skip` with a
+ * named reason). Each check connects a fresh driver, drives `start` + the
+ * fixture's `prepare`, and disposes the driver. Exported for the kit's own
+ * unit tests; adopters call `runGlspConformance`.
+ */
+export function buildGlspChecks<TAction, TDriver extends GlspConformanceDriver<TAction>>(
+   options: GlspConformanceOptions<TAction, TDriver>
+): ConformanceCheck[] {
+   const { connect } = options;
+   const checks: ConformanceCheck[] = [];
+
+   for (const diagram of options.diagrams) {
+      const tag = `[${diagram.diagramType}]`;
+
+      checks.push({
+         title: `start() initialises a client session ${tag}`,
+         body: async () => {
+            const driver = await connect();
+            try {
+               await driver.start();
+            } finally {
+               driver.dispose();
+            }
+         }
+      });
+
+      checks.push({
+         title: `RequestModel responds with ${diagram.expectedResponseKind} ${tag}`,
+         body: async () => {
+            const driver = await connect();
+            try {
+               await driver.start();
+               await diagram.prepare(driver);
+               driver.dispatch(diagram.requestModel());
+               const response = await driver.nextAction(diagram.expectedResponseKind);
+               if (diagram.expectResponse) {
+                  assert.ok(diagram.expectResponse(response), `expectResponse was false for the ${diagram.expectedResponseKind} response`);
+               }
+            } finally {
+               driver.dispose();
+            }
+         }
+      });
+
+      const operation = diagram.createOperation;
+      if (operation) {
+         checks.push({
+            title: `create operation mutates the source model ${tag}`,
+            body: async () => {
+               const driver = await connect();
+               try {
+                  await driver.start();
+                  await diagram.prepare(driver);
+                  driver.dispatch(diagram.requestModel());
+                  await driver.nextAction(diagram.expectedResponseKind);
+                  driver.dispatch(operation.action(driver));
+                  await driver.nextAction(operation.expectedResponseKind);
+                  assert.ok(
+                     operation.expectMutated(driver),
+                     'expectMutated was false — the create operation did not mutate the source model'
+                  );
+               } finally {
+                  driver.dispose();
+               }
+            }
+         });
+      } else {
+         checks.push({
+            title: `create operation mutates the source model ${tag}`,
+            skipReason: 'fixture supplied no createOperation'
+         });
+      }
+   }
+
+   return checks;
+}