@hydranium/conformance 1.0.0-next.11 → 1.0.0-next.111

package/lib/model.d.ts

@@ -6,6 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
+import type { Locale } from '@hydranium/protocol';
 /**
  * A fixture value that may be given directly or DEFERRED to check time.
  *
@@ -67,6 +68,45 @@ export interface EditSpec {
     readonly to: Deferred<string>;
     readonly expect: (root: unknown) => boolean;
 }
+/**
+ * A reference-picker query for an element that does not exist yet, plus the
+ * candidate the adopter expects it to offer.
+ *
+ * **The URI a create-element flow holds is a FOLDER**, because the file is not
+ * written until the dialog is confirmed. A folder URI names no file and so
+ * carries no extension, which is the one shape a head cannot route to a grammar
+ * by URI alone — it has to resolve the language some other way. That makes this
+ * the create dialog's load-bearing precondition and the reason the query is
+ * worth a conformance check of its own: a head that gets it wrong answers no
+ * candidates or throws, and the dialog never opens.
+ */
+export interface ReferenceQuerySpec {
+    /** AST type of the element being created — the synthetic source's own type. */
+    readonly type: string;
+    /** The reference property on the source (or on `syntheticPath`'s leaf) whose candidates the picker fills. */
+    readonly property: string;
+    /**
+     * Steps from the synthetic source down to the node holding `property`, when
+     * the reference is not on the source itself. Each step is
+     * `[containerProperty, type]` — the kit builds the `SyntheticStep`s, so the
+     * fixture names no protocol type.
+     */
+    readonly path?: ReadonlyArray<readonly [containerProperty: string, type: string]>;
+    /**
+     * Folder the create flow asks at. {@link Deferred} because a fixture may name
+     * a workspace the driver's `connect` only just created. Defaults to the parent
+     * of `valid.uri`, which is the folder a sibling of the valid model would go
+     * into — the common case, so most fixtures supply only `type` + `property`.
+     */
+    readonly folderUri?: Deferred<string>;
+    /**
+     * A candidate label the query MUST offer. Without it an empty result passes,
+     * and empty is exactly what the defect this check exists for produces — so
+     * the expectation is what makes the check discriminating rather than a
+     * smoke test.
+     */
+    readonly expectCandidate: string;
+}
 /**
  * The per-language fixture. `valid` and `invalid` are defined once and reused
  * across heads; the two extras are per-head opt-ins.
@@ -83,6 +123,9 @@ export interface EditSpec {
  *   uses `invalid.text` and never calls `edit.expect`, so an LSP-only adopter
  *   has nothing to supply here.
  * - `completionPosition` — read by the **LSP slice only**.
+ * - `referenceQuery` — read by the **data slice only**, and only when the
+ *   driver supplies `references` (the reference surface is opt-in on the head
+ *   too, so both halves have to be present for the check to run).
  *
  * Both extras are optional and their checks report *skipped* when absent,
  * rather than silently not running. Making either mandatory would defeat the
@@ -107,5 +150,67 @@ export interface LanguageFixture {
         readonly line: number;
         readonly character: number;
     };
+    /**
+     * Optional: the create-dialog reference query. Read by the **data slice
+     * only**, and only when the driver exposes the opt-in reference surface.
+     */
+    readonly referenceQuery?: ReferenceQuerySpec;
+    /**
+     * Optional: a second document that REFERENCES {@link valid}, so the data
+     * slice can provoke a CASCADE — a rebuild of this document caused by
+     * editing the one it points at, with its own text never touched.
+     *
+     * Opt-in because a grammar need not have cross-document references at all,
+     * and because only the adopter knows which pair of documents forms one.
+     * Supplying it IS the claim that editing `valid` rebuilds this document; the
+     * check then holds the head to reporting that on `onDocumentsBuilt`, which
+     * is the only channel that can carry it — the document has no subscriber and
+     * its file did not change, so neither the update channel nor a filesystem
+     * watcher can.
+     */
+    readonly dependent?: ConformanceModel;
+    /**
+     * Optional: a locale plus the sentence the server must publish in it. Read
+     * by the **LSP slice only**.
+     */
+    readonly renderedDiagnostic?: RenderedDiagnosticSpec;
+}
+/**
+ * A locale, and one sentence the server must produce in it for the `invalid`
+ * fixture.
+ *
+ * **Opt-in, and it has to be.** The framework ships no catalogue and selects no
+ * locale, so a server that installs no renderer correctly publishes English —
+ * mandating this check would fail every adopter without i18n for doing the right
+ * thing. Supplying the field is the adopter saying "I render server-side, hold me
+ * to it".
+ *
+ * `expected` is a SUBSTRING, not the whole message. The kit owns no grammar, so
+ * it cannot know how many diagnostics `invalid` produces or in what order, and
+ * an adopter should be able to pin the translated fragment without restating a
+ * sentence they may reword. A substring long enough to be wrong if the render
+ * did not happen is the whole requirement.
+ *
+ * `absentWithoutLocale` is what makes the check a pair rather than a single
+ * assertion: "the message contains X" also passes for a server whose English
+ * happens to contain X, and for one that renders regardless of locale. Naming
+ * the fragment that must DISAPPEAR when no locale is declared is what
+ * distinguishes those.
+ */
+export interface RenderedDiagnosticSpec {
+    /** The locale to declare at `initialize` — the tag whose catalogue the server has. */
+    readonly locale: Locale;
+    /** A fragment of the translated sentence, present in some diagnostic of the `invalid` fixture. */
+    readonly expected: string;
+    /**
+     * A fragment that must be absent once `locale` is declared, and present
+     * without it — normally a piece of the server's own English.
+     *
+     * Optional only because a catalogue may translate a message whose English
+     * shares no distinctive fragment with it. Omitting it drops the second half
+     * of the pair and leaves a check that a render-nothing server can pass; the
+     * kit reports that rather than pretending otherwise.
+     */
+    readonly absentWithLocale?: string;
 }
 //# sourceMappingURL=model.d.ts.map

package/lib/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,wBAAwB,CAM9E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACtB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACtF"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,wBAAwB,CAM9E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACtB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6GAA6G;IAC7G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAClF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,eAAe;IAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACpF;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;IAC7C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,sBAAsB;IACpC,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACrC"}

package/lib/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA2ClF,8CAA8C;AAC9C,MAAM,UAAU,eAAe,CAAI,KAAkB;IAClD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAAiB,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB;IACjD,OAAO;QACJ,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC;QAC/B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;KACnC,CAAC;AACL,CAAC"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA6ClF,8CAA8C;AAC9C,MAAM,UAAU,eAAe,CAAI,KAAkB;IAClD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAAiB,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB;IACjD,OAAO;QACJ,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC;QAC/B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;KACnC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/conformance",
-  "version": "1.0.0-next.11",
+  "version": "1.0.0-next.111",
   "description": "Protocol conformance kit (TCK) for hydranium adopters. Per-head slices (/data, /lsp, /glsp) of fixture-parameterized, protocol-only smoke checks an adopter runs against its own server.",
   "keywords": [
     "hydranium",
@@ -88,7 +88,7 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.11",
+    "@hydranium/protocol": "1.0.0-next.111",
     "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.12",
     "jest": "^29.7.0",
@@ -98,7 +98,7 @@
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.11",
+    "@hydranium/protocol": "1.0.0-next.111",
     "@jest/globals": "^29.0.0",
     "vitest": "^4.0.0"
   },

package/src/data/index.ts

@@ -10,24 +10,36 @@
 /**
  * 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.
+ * {@link DataServerProtocol} proxy (plus the captured client notifications),
+ * 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 {
+   isConflictError,
+   ReferenceSource,
+   SyntheticStep,
+   TransferDocument,
+   type TransferDiagnostic,
+   type TransferElement
+} from '@hydranium/protocol';
+import type {
+   DataServerProtocol,
+   ReferenceServerProtocol,
+   TransferDocumentsBuiltEvent,
+   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
+ * through its protocol-native proxy plus the captured client-side
+ * notifications. 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
+ * `events`, `builds` and `dispose`) with NO adapter. `extends Harness` gives the kit the
  * universal `dispose()` teardown.
  *
  * The kit seeds documents purely through the proxy: `updateModelDocument` is
@@ -43,6 +55,17 @@ export interface DataConformanceDriver<
    readonly proxy: DataServerProtocol<TTransfer, TDiagnostic>;
    /** Captured `onDocumentUpdated` events, append order — the subscription check's observation target. */
    readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+   /** Captured `onDocumentsBuilt` events, append order — the cascade check's observation target. */
+   readonly builds: ReadonlyArray<TransferDocumentsBuiltEvent>;
+   /**
+    * The opt-in reference surface, when the head serves it.
+    *
+    * Separate from {@link proxy} because `ReferenceServerProtocol` is NOT part
+    * of `DataServerProtocol` — a head may serve documents and no references at
+    * all. Absent means the reference check reports skipped with a named reason
+    * rather than failing a head that never claimed the surface.
+    */
+   readonly references?: ReferenceServerProtocol<TTransfer>;
 }
 
 /** Options for `runDataConformance`. */
@@ -91,7 +114,7 @@ const SEEDER = 'conformance-seeder';
  * 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
+ * optional: every check that needs one reports skipped when it is absent. See
  * {@link LanguageFixture} for which slice reads which field.
  */
 export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic>(
@@ -178,7 +201,7 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
    });
 
    for (const language of options.languages) {
-      const { valid, invalid, edit } = language;
+      const { valid, invalid, edit, dependent } = language;
       const tag = `[${valid.languageId}]`;
 
       checks.push({
@@ -189,7 +212,7 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
                // 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 });
+               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text, basedOn: 'anything' });
                // `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
@@ -224,7 +247,7 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
             const driver = await connect();
             try {
                const model = resolveModel(invalid);
-               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text });
+               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text, basedOn: 'anything' });
                // 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
@@ -237,6 +260,101 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
          }
       });
 
+      checks.push({
+         title: `a diagnostic carrying a framework message code also carries its params ${tag}`,
+         body: async () => {
+            const driver = await connect();
+            try {
+               const model = resolveModel(invalid);
+               await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text, basedOn: 'anything' });
+               const document = await driver.proxy.getModelDocument({ uri: model.uri, includeDiagnostics: true });
+
+               // Conditional rather than fixture-driven, and deliberately so: what
+               // an `invalid` fixture provokes is the adopter's choice, and a
+               // syntactic error legitimately carries no identity at all. The
+               // invariant is that the identity travels WHOLE or not — a `code`
+               // without `params` is the half-state that renders a translated
+               // template with its placeholders left standing, and it is
+               // reachable only by overriding `toTransferDiagnostic`.
+               const halfIdentities = document.diagnostics.filter(
+                  diagnostic =>
+                     typeof diagnostic.code === 'string' && diagnostic.code.startsWith('hydranium/') && diagnostic.params === undefined
+               );
+               assert.deepStrictEqual(
+                  halfIdentities.map(diagnostic => diagnostic.code),
+                  [],
+                  'diagnostics carry a framework message code with no params, so a translating surface cannot render them'
+               );
+            } finally {
+               driver.dispose();
+            }
+         }
+      });
+
+      // The create-dialog query, and the reason it is its own check: it is the
+      // only request a head receives whose URI names no file. Everything else
+      // in this battery addresses a document, so a head that routes purely by
+      // URI extension passes all of them and still cannot open a create dialog.
+      //
+      // Doubly opt-in — the fixture must name a query AND the driver must serve
+      // the reference surface — because either half missing means the head never
+      // claimed this behaviour. The reasons are reported separately so a skip
+      // says which half is absent.
+      const referenceQuery = language.referenceQuery;
+      const referenceSkipReason = !referenceQuery
+         ? 'fixture supplies no `referenceQuery` (omit it if this language has no create-element dialog)'
+         : undefined;
+
+      checks.push({
+         title: `findReferenceCandidates answers for a synthetic source at a folder URI ${tag}`,
+         skipReason: referenceSkipReason,
+         body: referenceQuery
+            ? async () => {
+                 const driver = await connect();
+                 try {
+                    if (!driver.references) {
+                       // Checked here rather than in `skipReason`: the driver only
+                       // exists once `connect` has run, and skip reasons are
+                       // computed while the battery is being planned.
+                       return;
+                    }
+                    const model = resolveModel(valid);
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text, basedOn: 'anything' });
+
+                    // Default to the folder holding the valid model: a sibling of
+                    // it is where a create flow would put the new file.
+                    const folderUri = referenceQuery.folderUri
+                       ? resolveDeferred(referenceQuery.folderUri)
+                       : model.uri.slice(0, model.uri.lastIndexOf('/'));
+                    assert.ok(
+                       folderUri.length > 0 && folderUri !== model.uri,
+                       `could not derive a folder URI from ${model.uri}; supply referenceQuery.folderUri`
+                    );
+
+                    const candidates = await driver.references.findReferenceCandidates({
+                       source: ReferenceSource.synthetic(folderUri, referenceQuery.type),
+                       syntheticPath: referenceQuery.path?.map(([containerProperty, type]) => SyntheticStep.of(containerProperty, type)),
+                       property: referenceQuery.property
+                    });
+
+                    // The expected label, not merely a non-empty array: the defect
+                    // this guards against answers `[]`, and an empty result is
+                    // also what a head with a genuinely empty index answers, so
+                    // only a named candidate tells the two apart.
+                    const labels = candidates.map(candidate => candidate.label);
+                    assert.ok(
+                       labels.includes(referenceQuery.expectCandidate),
+                       `findReferenceCandidates at the folder ${folderUri} did not offer ${JSON.stringify(
+                          referenceQuery.expectCandidate
+                       )}; got [${labels.join(', ')}]`
+                    );
+                 } finally {
+                    driver.dispose();
+                 }
+              }
+            : undefined
+      });
+
       // 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)';
@@ -249,8 +367,13 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
                  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) });
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text, basedOn: 'anything' });
+                    await driver.proxy.updateModelDocument({
+                       uri: model.uri,
+                       clientId: AUTHOR,
+                       model: resolveDeferred(edit.to),
+                       basedOn: 'anything'
+                    });
                     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 {
@@ -260,6 +383,108 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
             : undefined
       });
 
+      checks.push({
+         title: `updateModelDocument arms the conflict gate on a based-on snapshot version ${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, basedOn: 'anything' });
+
+                    // The version the gate is meant to accept, read BEFORE the
+                    // foreign edit that supersedes it.
+                    const stale = await driver.proxy.getModelDocument({ uri: model.uri });
+                    await driver.proxy.updateModelDocument({
+                       uri: model.uri,
+                       clientId: SEEDER,
+                       model: resolveDeferred(edit.to),
+                       basedOn: 'anything'
+                    });
+
+                    let rejection: unknown;
+                    await driver.proxy
+                       .updateModelDocument({
+                          uri: model.uri,
+                          clientId: AUTHOR,
+                          model: model.text,
+                          basedOn: stale.version
+                       })
+                       .catch((error: unknown) => {
+                          rejection = error;
+                       });
+                    assert.ok(
+                       isConflictError(rejection),
+                       `a write based on the superseded v${stale.version} was not refused: ${String(rejection)}`
+                    );
+
+                    // The other half, and it is not optional: a head that refused
+                    // EVERY write would satisfy the assertion above on its own, so
+                    // the gate has to be shown accepting a current snapshot too.
+                    const fresh = await driver.proxy.getModelDocument({ uri: model.uri });
+                    await driver.proxy.updateModelDocument({
+                       uri: model.uri,
+                       clientId: AUTHOR,
+                       model: resolveDeferred(edit.to),
+                       basedOn: fresh.version
+                    });
+                 } finally {
+                    driver.dispose();
+                 }
+              }
+            : undefined
+      });
+
+      // Opt-in twice over: the cascade needs an edit to provoke it AND a second
+      // document that references the first to be provoked.
+      const cascadeSkipReason =
+         'fixture supplies no `dependent` (a document referencing `valid`), so no cascade can be provoked over the protocol';
+
+      checks.push({
+         title: `editing a document reports its unwatched dependent as built ${tag}`,
+         skipReason: edit && dependent ? undefined : dependent ? editSkipReason : cascadeSkipReason,
+         body:
+            edit && dependent
+               ? async () => {
+                    const driver = await connect();
+                    try {
+                       const model = resolveModel(valid);
+                       const other = resolveModel(dependent);
+                       await driver.proxy.updateModelDocument({ uri: model.uri, clientId: SEEDER, model: model.text, basedOn: 'anything' });
+                       await driver.proxy.updateModelDocument({ uri: other.uri, clientId: SEEDER, model: other.text, basedOn: 'anything' });
+                       // Watch ONLY the referenced document. The dependent is left
+                       // unwatched on purpose: that is the state in which no other
+                       // channel can report it, and the state a workspace view is in
+                       // for every document it displays without opening.
+                       await driver.proxy.watchModelDocument({ uri: model.uri, clientId: SUBSCRIBER });
+                       const before = driver.builds.length;
+
+                       await driver.proxy.updateModelDocument({
+                          uri: model.uri,
+                          clientId: AUTHOR,
+                          model: resolveDeferred(edit.to),
+                          basedOn: 'anything'
+                       });
+
+                       await waitFor(() => driver.builds.slice(before).some(event => event.uris.includes(other.uri)), {
+                          message: `no onDocumentsBuilt event named ${other.uri} after editing the document it references`
+                       });
+                       const reported = driver.builds.slice(before).flatMap(event => [...event.uris]);
+                       // The watched document is excluded: its watcher already heard
+                       // about it on the update channel, and repeating it here would
+                       // be the bandwidth the per-URI gate exists to avoid.
+                       assert.ok(
+                          !reported.includes(model.uri),
+                          `onDocumentsBuilt named the WATCHED ${model.uri}; it is reported on the update channel instead`
+                       );
+                    } finally {
+                       driver.dispose();
+                    }
+                 }
+               : undefined
+      });
+
       checks.push({
          title: `subscribe + update delivers an onDocumentUpdated event with the originating clientId ${tag}`,
          skipReason: edit ? undefined : editSkipReason,
@@ -268,9 +493,14 @@ export function buildDataChecks<TTransfer extends TransferElement, TDiagnostic e
                  const driver = await connect();
                  try {
                     const model = resolveModel(valid);
-                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: SEEDER, model: model.text });
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: SEEDER, model: model.text, basedOn: 'anything' });
                     await driver.proxy.watchModelDocument({ uri: model.uri, clientId: SUBSCRIBER });
-                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: resolveDeferred(edit.to) });
+                    await driver.proxy.updateModelDocument({
+                       uri: model.uri,
+                       clientId: AUTHOR,
+                       model: resolveDeferred(edit.to),
+                       basedOn: 'anything'
+                    });
                     await waitFor(() => driver.events.some(event => event.sourceClientId === AUTHOR), {
                        message: `no onDocumentUpdated event for ${model.uri} after the post-subscription update`
                     });