@hydranium/conformance 1.0.0-next.24 → 1.0.0-next.242

package/lib/data/index.js

@@ -9,26 +9,100 @@
 /**
  * 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 } from '@hydranium/protocol';
+import { asModelVersion, FRAMEWORK_CLIENT_IDS, isConflictError, isDocumentNotOpenError, isDuplicateClientIdError, isReservedClientIdError, isSessionClosedError, ReferenceSource, SyntheticStep, TransferDocument, UNKNOWN_CLIENT_ID } from '@hydranium/protocol';
 import { waitFor } from '@hydranium/protocol/testing';
 import { resolveDeferred, resolveModel } from '../model.js';
-/** 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. */
+/** Client id the kit subscribes under; a watch needs no session. */
 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.
+ * A fresh session id per check. A fixed one would be refused as a duplicate
+ * by a head whose `connect` reuses one server across checks, whenever an
+ * earlier check failed before ending its session.
  */
-const SEEDER = 'conformance-seeder';
+function sessionId(label = 'conformance-session') {
+    return `${label}#${globalThis.crypto.randomUUID()}`;
+}
+/** Register a session under a fresh id labelled `label`, and answer the id. */
+async function startSession(driver, label) {
+    const clientId = sessionId(label);
+    await driver.proxy.createSession({ clientId, label });
+    return clientId;
+}
+/**
+ * Create `model` for the session `clientId`, then open it, since a fixture may
+ * name a document that exists nowhere but in the kit. A failed create is
+ * dropped when the open succeeds, so a head whose create is broken fails only
+ * the create check; an open that fails reports both failures.
+ */
+async function openOrCreate(driver, clientId, model) {
+    const created = await rejectionOf(driver.proxy.createModelDocument({ uri: model.uri, clientId, text: model.text }));
+    const opened = await rejectionOf(driver.proxy.openModelDocument({ uri: model.uri, clientId }));
+    if (opened !== undefined) {
+        throw new Error(`Could not seed ${model.uri}: ${String(opened)}; creating it failed with ${String(created)}`, { cause: opened });
+    }
+}
+/**
+ * Write `model` to its URI under a new session labelled `label`, and answer the
+ * session's id. The session keeps the document open until the driver is
+ * disposed: closing it would revert the document to its file, which holds
+ * another text or none.
+ */
+async function seed(driver, model, label = 'conformance-seeder') {
+    const clientId = await startSession(driver, label);
+    await openOrCreate(driver, clientId, model);
+    await driver.proxy.updateModelDocument({ uri: model.uri, clientId, model: model.text, baseVersion: 'any' });
+    return clientId;
+}
+/** A new session labelled `label` with `uri` open, for a write after the seed; answers its id. */
+async function openAs(driver, uri, label = 'conformance-author') {
+    const clientId = await startSession(driver, label);
+    await driver.proxy.openModelDocument({ uri, clientId });
+    return clientId;
+}
+/**
+ * Register `clientId` on `driver`, retrying while the server still refuses it
+ * as a duplicate, for up to `boundMs`; the last refusal is thrown.
+ */
+async function registerWithin(driver, clientId, boundMs) {
+    const deadline = Date.now() + boundMs;
+    for (;;) {
+        const refusal = await rejectionOf(driver.proxy.createSession({ clientId }));
+        if (refusal === undefined) {
+            return;
+        }
+        if (!isDuplicateClientIdError(refusal) || Date.now() >= deadline) {
+            throw refusal;
+        }
+        await new Promise(resolveDelay => setTimeout(resolveDelay, 20));
+    }
+}
+/** A URI beside `uri` in its folder, its file name prefixed with `prefix`, so the language and project stay the fixture's. */
+function siblingOf(uri, prefix) {
+    const slash = uri.lastIndexOf('/') + 1;
+    return `${uri.slice(0, slash)}${prefix}${uri.slice(slash)}`;
+}
+/**
+ * Read `uri` until `settled` holds of the answer, for up to two seconds; fail
+ * with `message` after that. For an effect a head may finish after its request
+ * answered, such as the revert of a last close. A refused read reaches
+ * `settled` as `undefined`.
+ */
+async function readUntil(driver, uri, settled, message) {
+    const deadline = Date.now() + 2_000;
+    while (!settled(await driver.proxy.getModelDocument({ uri }).catch(() => undefined))) {
+        assert.ok(Date.now() < deadline, message);
+        await new Promise(resolveDelay => setTimeout(resolveDelay, 20));
+    }
+}
+/** Settle `promise` into its rejection, or `undefined` when it resolved. */
+async function rejectionOf(promise) {
+    return promise.then(() => undefined, (error) => error);
+}
 /**
  * Build the data-server check battery: server-level checks once, then the
  * grammar-bearing checks per language. Each check connects a fresh driver
@@ -36,11 +110,11 @@ 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(options) {
-    const { connect, expectsProjects } = options;
+    const { connect, attach, expectsProjects } = options;
     const checks = [];
     // Split from `waitForReady` so a failure names which of the two broke.
     //
@@ -98,6 +172,43 @@ export function buildDataChecks(options) {
             }
             : undefined
     });
+    checks.push({
+        title: 'createSession refuses an id already live, and frees it once the session ends',
+        body: async () => {
+            const driver = await connect();
+            try {
+                const clientId = await startSession(driver, 'conformance-session');
+                const duplicate = await rejectionOf(driver.proxy.createSession({ clientId }));
+                assert.ok(isDuplicateClientIdError(duplicate), `a second createSession under a live id was not refused: ${String(duplicate)}`);
+                await driver.proxy.closeSession({ clientId });
+                // The other half: a head that refused every id would pass the
+                // assertion above on its own.
+                await driver.proxy.createSession({ clientId });
+                await driver.proxy.closeSession({ clientId });
+            }
+            finally {
+                driver.dispose();
+            }
+        }
+    });
+    checks.push({
+        title: 'createSession refuses every id the framework reserves, not as a duplicate',
+        body: async () => {
+            const driver = await connect();
+            try {
+                // Every id: a head that refuses only some passes a single case. A
+                // reserved id never frees up, so a caller retrying on a duplicate
+                // has to be able to tell this refusal apart.
+                for (const clientId of FRAMEWORK_CLIENT_IDS) {
+                    const refusal = await rejectionOf(driver.proxy.createSession({ clientId }));
+                    assert.ok(isReservedClientIdError(refusal), `createSession under the reserved id ${clientId} was not refused as reserved: ${String(refusal)}`);
+                }
+            }
+            finally {
+                driver.dispose();
+            }
+        }
+    });
     checks.push({
         title: 'waitForReady resolves rather than hanging or rejecting',
         body: async () => {
@@ -114,7 +225,7 @@ export function buildDataChecks(options) {
         }
     });
     for (const language of options.languages) {
-        const { valid, invalid, edit } = language;
+        const { valid, invalid, edit, dependent } = language;
         const tag = `[${valid.languageId}]`;
         checks.push({
             title: `getModelDocument(valid) returns a coherent envelope ${tag}`,
@@ -124,7 +235,7 @@ export function buildDataChecks(options) {
                     // 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 seed(driver, model);
                     // `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
@@ -135,12 +246,14 @@ export function buildDataChecks(options) {
                     // 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);
+                    const { model: snapshot } = TransferDocument.assertLoaded(document);
+                    const { root } = snapshot;
                     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, []);
+                    assert.ok(Number.isInteger(snapshot.version), `getModelDocument(valid) returned a non-integer version: ${String(snapshot.version)}`);
+                    assert.strictEqual(typeof snapshot.hash, 'string', 'getModelDocument(valid) returned a model with no hash');
+                    assert.deepStrictEqual(snapshot.diagnostics, []);
                 }
                 finally {
                     driver.dispose();
@@ -153,21 +266,387 @@ export function buildDataChecks(options) {
                 const driver = await connect();
                 try {
                     const model = resolveModel(invalid);
-                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId: AUTHOR, model: model.text });
+                    await seed(driver, model);
                     // 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');
+                    assert.ok((document.model?.diagnostics?.length ?? 0) >= 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.
+        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 seed(driver, model);
+                    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.model?.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();
+                }
+            }
+        });
+        checks.push({
+            title: `a session writes only a document it has open ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    await seed(driver, model);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    const write = { uri: model.uri, clientId, model: model.text, baseVersion: 'any' };
+                    const unopened = await rejectionOf(driver.proxy.updateModelDocument(write));
+                    assert.ok(isDocumentNotOpenError(unopened), `a session wrote a document it never opened: ${String(unopened)}`);
+                    await driver.proxy.openModelDocument({ uri: model.uri, clientId });
+                    await driver.proxy.updateModelDocument(write);
+                    await driver.proxy.closeModelDocument({ uri: model.uri, clientId });
+                    const closed = await rejectionOf(driver.proxy.updateModelDocument(write));
+                    assert.ok(isDocumentNotOpenError(closed), `a session wrote a document after closing it: ${String(closed)}`);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a session saves only a document it has open ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    await seed(driver, model);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    const save = { uri: model.uri, clientId, model: model.text, baseVersion: 'any' };
+                    const unopened = await rejectionOf(driver.proxy.saveModelDocument(save));
+                    assert.ok(isDocumentNotOpenError(unopened), `a session saved a document it never opened: ${String(unopened)}`);
+                    // The other half: a head refusing every session save would pass
+                    // the assertion above on its own.
+                    await driver.proxy.openModelDocument({ uri: model.uri, clientId });
+                    await driver.proxy.saveModelDocument(save);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a document request under an id no session was registered for fails ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    await seed(driver, model);
+                    const clientId = sessionId('conformance-unregistered');
+                    // Opened or written under an id that is no session, a document
+                    // would stay open for a client whose end nothing ever reports.
+                    const open = await rejectionOf(driver.proxy.openModelDocument({ uri: model.uri, clientId }));
+                    assert.ok(isSessionClosedError(open), `a document opened under an unregistered id: ${String(open)}`);
+                    const write = await rejectionOf(driver.proxy.updateModelDocument({ uri: model.uri, clientId, model: model.text, baseVersion: 'any' }));
+                    assert.ok(isSessionClosedError(write), `a document was written under an unregistered id: ${String(write)}`);
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `ending a connection ends its sessions ${tag}`,
+            skipReason: attach ? undefined : 'options supply no `attach` (a second connection to the same server outlives the ended one)',
+            body: attach
+                ? async () => {
+                    const driver = await connect();
+                    let driverOpen = true;
+                    try {
+                        const model = resolveModel(valid);
+                        await seed(driver, model);
+                        const clientId = await startSession(driver, 'conformance-session');
+                        await driver.proxy.openModelDocument({ uri: model.uri, clientId });
+                        const sibling = await attach(driver);
+                        try {
+                            driverOpen = false;
+                            driver.dispose();
+                            // Refused as a duplicate while the ended connection's
+                            // session lives on, which over a socket it does until the
+                            // server has seen the close; so retried, within a bound.
+                            await registerWithin(sibling, clientId, 2_000);
+                            const write = await rejectionOf(sibling.proxy.updateModelDocument({ uri: model.uri, clientId, model: model.text, baseVersion: 'any' }));
+                            assert.ok(isDocumentNotOpenError(write), `a document stayed open after its connection ended: ${String(write)}`);
+                            await sibling.proxy.closeSession({ clientId });
+                        }
+                        finally {
+                            sibling.dispose();
+                        }
+                    }
+                    finally {
+                        if (driverOpen) {
+                            driver.dispose();
+                        }
+                    }
+                }
+                : undefined
+        });
+        checks.push({
+            title: `closeSession closes every document the session had open ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    await seed(driver, model);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    await driver.proxy.openModelDocument({ uri: model.uri, clientId });
+                    await driver.proxy.closeSession({ clientId });
+                    // Observed through a new session under the same id: one that
+                    // inherited the ended session's open would write without opening.
+                    await driver.proxy.createSession({ clientId });
+                    const write = await rejectionOf(driver.proxy.updateModelDocument({ uri: model.uri, clientId, model: model.text, baseVersion: 'any' }));
+                    assert.ok(isDocumentNotOpenError(write), `a document stayed open after its session ended: ${String(write)}`);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `createModelDocument creates a document open for the session, and refuses one that exists ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    await seed(driver, model);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    const createdUri = siblingOf(model.uri, 'conformance-created-');
+                    const created = await driver.proxy.createModelDocument({ uri: createdUri, clientId, text: model.text });
+                    const { model: createdModel } = TransferDocument.assertLoaded(created);
+                    // Written without an open: only the create can have opened it.
+                    await driver.proxy.updateModelDocument({ uri: createdUri, clientId, model: model.text, baseVersion: createdModel.version });
+                    const existing = await rejectionOf(driver.proxy.createModelDocument({ uri: model.uri, clientId, text: model.text }));
+                    assert.ok(existing !== undefined, `createModelDocument accepted ${model.uri}, which already exists`);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a write of the invalid model answers with its diagnostics ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(invalid);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    await openOrCreate(driver, clientId, model);
+                    // Another text first, so that the invalid one is a change: the
+                    // answer to a write that changes nothing can carry the
+                    // diagnostics of an earlier validation. This does not prove the
+                    // answer waited for this write's validation, only that it
+                    // carries diagnostics at all.
+                    const firstText = resolveDeferred(valid.text);
+                    await driver.proxy.updateModelDocument({ uri: model.uri, clientId, model: firstText, baseVersion: 'any' });
+                    // The answer alone, with no read after it: a caller that shows
+                    // the problems of what it wrote should not need a second
+                    // request, and a read could find a later write's state.
+                    const answer = await driver.proxy.updateModelDocument({ uri: model.uri, clientId, model: model.text, baseVersion: 'any' });
+                    assert.ok((answer.model?.diagnostics?.length ?? 0) >= 1, 'writing the invalid model answered with no diagnostics');
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a created document never saved leaves with its last close ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    const uri = siblingOf(model.uri, 'conformance-unsaved-');
+                    const clientId = await startSession(driver, 'conformance-session');
+                    await driver.proxy.createModelDocument({ uri, clientId, text: model.text });
+                    // Served before the close, so an envelope without a model after
+                    // it is the close's doing and not the head's answer for every
+                    // created document.
+                    TransferDocument.assertLoaded(await driver.proxy.getModelDocument({ uri }));
+                    await driver.proxy.closeSession({ clientId });
+                    // It has no file to go back to, so no text is left to serve, and
+                    // the protocol answers a URI with no document with an envelope
+                    // that has no model, not with a refusal.
+                    await readUntil(driver, uri, document => document !== undefined && !TransferDocument.isLoaded(document), `${uri}, created and never saved, was not answered with an envelope without a model after its last close`);
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a document is dirty while its text differs from its file, and clean once saved ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    // Only `dirty` is asserted, so any second text serves.
+                    const unsaved = resolveDeferred(invalid.text);
+                    const uri = siblingOf(model.uri, `conformance-saved-${globalThis.crypto.randomUUID()}-`);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    await driver.proxy.createModelDocument({ uri, clientId, text: model.text });
+                    const saved = await driver.proxy.saveModelDocument({ uri, clientId, model: model.text, baseVersion: 'any' });
+                    assert.strictEqual(saved.text?.dirty, false, `the save of ${uri} answered dirty: ${String(saved.text?.dirty)}, not false`);
+                    assert.strictEqual(saved.persisted?.version, saved.text?.version, `the save of ${uri} answered it wrote v${String(saved.persisted?.version)}, not the v${String(saved.text?.version)} it holds`);
+                    const edited = await driver.proxy.updateModelDocument({ uri, clientId, model: unsaved, baseVersion: 'any' });
+                    assert.strictEqual(edited.text?.dirty, true, `an unsaved write of ${uri} answered dirty: ${String(edited.text?.dirty)}, not true`);
+                    const resaved = await driver.proxy.saveModelDocument({ uri, clientId, model: unsaved, baseVersion: 'any' });
+                    assert.strictEqual(resaved.text?.dirty, false, `the second save of ${uri} answered dirty: ${String(resaved.text?.dirty)}, not false`);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `persisting writes the text a document holds as it is, and refuses a stale base version ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    // Trailing blank lines no serialiser writes, so a head that
+                    // persists a re-serialised model rather than the text shows.
+                    const held = `${model.text}\n\n`;
+                    const uri = siblingOf(model.uri, `conformance-persisted-${globalThis.crypto.randomUUID()}-`);
+                    const writer = await startSession(driver, 'conformance-writer');
+                    const created = await driver.proxy.createModelDocument({ uri, clientId: writer, text: model.text });
+                    const written = await driver.proxy.updateModelDocument({ uri, clientId: writer, model: held, baseVersion: 'any' });
+                    const persister = await openAs(driver, uri, 'conformance-persister');
+                    const stale = await rejectionOf(driver.proxy.persistModelDocument({
+                        uri,
+                        clientId: persister,
+                        baseVersion: TransferDocument.assertLoaded(created).model.version
+                    }));
+                    assert.ok(isConflictError(stale), `persisting ${uri} on a stale base version did not conflict: ${String(stale)}`);
+                    const base = TransferDocument.assertLoaded(written).model.version;
+                    const persisted = await driver.proxy.persistModelDocument({ uri, clientId: persister, baseVersion: base });
+                    assert.strictEqual(persisted.persisted?.version, base, `the persist of ${uri} answered it wrote v${String(persisted.persisted?.version)}, not the v${base} it was based on`);
+                    assert.strictEqual(persisted.text?.dirty, false, `the persist of ${uri} answered dirty: ${String(persisted.text?.dirty)}`);
+                    assert.strictEqual(persisted.text?.hash, written.text?.hash, `persisting ${uri} changed the text it holds`);
+                    // Read after the last close, which serves the file: read before
+                    // it, the held text answers and a file written wrong passes.
+                    await driver.proxy.closeSession({ clientId: writer });
+                    await driver.proxy.closeSession({ clientId: persister });
+                    const reader = await openAs(driver, uri, 'conformance-reader');
+                    const reread = await driver.proxy.getModelDocument({ uri });
+                    assert.strictEqual(reread.text?.hash, written.text?.hash, `the file persisted for ${uri} is not the text it held`);
+                    await driver.proxy.closeSession({ clientId: reader });
+                }
+                finally {
+                    driver.dispose();
+                }
+            }
+        });
+        checks.push({
+            title: `a document's text hash is equal for equal text and differs for different text ${tag}`,
+            body: async () => {
+                const driver = await connect();
+                try {
+                    const model = resolveModel(valid);
+                    // Only the text is compared, so any second text serves.
+                    const other = resolveDeferred(invalid.text);
+                    const uri = siblingOf(model.uri, `conformance-hashed-${globalThis.crypto.randomUUID()}-`);
+                    const clientId = await startSession(driver, 'conformance-session');
+                    const created = await driver.proxy.createModelDocument({ uri, clientId, text: model.text });
+                    const edited = await driver.proxy.updateModelDocument({ uri, clientId, model: other, baseVersion: 'any' });
+                    // Back to the first text at a later version: the hash follows
+                    // the text, which is what a client compares across a revert.
+                    const restored = await driver.proxy.updateModelDocument({ uri, clientId, model: model.text, baseVersion: 'any' });
+                    assert.strictEqual(typeof created.text?.hash, 'string', `the create of ${uri} answered with no text hash`);
+                    assert.notStrictEqual(edited.text?.hash, created.text?.hash, `${uri} hashed a different text alike: ${String(edited.text?.hash)}`);
+                    assert.strictEqual(restored.text?.hash, created.text?.hash, `${uri} hashed its first text again as ${String(restored.text?.hash)}`);
+                    const read = await driver.proxy.getModelDocument({ uri });
+                    assert.strictEqual(read.text?.hash, restored.text?.hash, `a read of ${uri} hashed its text as ${String(read.text?.hash)}`);
+                    const absent = await driver.proxy.getModelDocument({
+                        uri: siblingOf(model.uri, `conformance-absent-${globalThis.crypto.randomUUID()}-`)
+                    });
+                    assert.strictEqual(absent.text, undefined, `an envelope with no document carried text ${JSON.stringify(absent.text)}`);
+                    await driver.proxy.closeSession({ clientId });
+                }
+                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 seed(driver, model);
+                        // 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: a check that needs a second, observably different model text
+        // takes it from `edit`, and skips without one.
         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}`,
@@ -177,10 +656,237 @@ export function buildDataChecks(options) {
                     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 seeder = await seed(driver, model);
+                        await driver.proxy.updateModelDocument({
+                            uri: model.uri,
+                            clientId: seeder,
+                            model: resolveDeferred(edit.to),
+                            baseVersion: 'any'
+                        });
                         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');
+                        assert.ok(edit.expect(document.model?.root), 'edit.expect(root) was false — the edit was not reflected by a follow-up get');
+                    }
+                    finally {
+                        driver.dispose();
+                    }
+                }
+                : undefined
+        });
+        checks.push({
+            title: `updateModelDocument arms the conflict gate on a base version ${tag}`,
+            skipReason: edit ? undefined : editSkipReason,
+            body: edit
+                ? async () => {
+                    const driver = await connect();
+                    try {
+                        const model = resolveModel(valid);
+                        const seeder = await seed(driver, model);
+                        const author = await openAs(driver, model.uri);
+                        // 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),
+                            baseVersion: 'any'
+                        });
+                        let rejection;
+                        await driver.proxy
+                            .updateModelDocument({
+                            uri: model.uri,
+                            clientId: author,
+                            model: model.text,
+                            baseVersion: TransferDocument.assertLoaded(stale).model.version
+                        })
+                            .catch((error) => {
+                            rejection = error;
+                        });
+                        assert.ok(isConflictError(rejection), `a write based on the superseded v${String(stale.model?.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),
+                            baseVersion: TransferDocument.assertLoaded(fresh).model.version
+                        });
+                    }
+                    finally {
+                        driver.dispose();
+                    }
+                }
+                : undefined
+        });
+        checks.push({
+            title: `the last close drops a document's unsaved text and keeps what its save wrote ${tag}`,
+            skipReason: edit ? undefined : editSkipReason,
+            body: edit
+                ? async () => {
+                    const driver = await connect();
+                    try {
+                        const model = resolveModel(valid);
+                        const edited = resolveDeferred(edit.to);
+                        const uri = siblingOf(model.uri, `conformance-reverted-${globalThis.crypto.randomUUID()}-`);
+                        const writer = await startSession(driver, 'conformance-writer');
+                        // Created with the edit, so that going back to the created
+                        // text instead of the saved one shows.
+                        await driver.proxy.createModelDocument({ uri, clientId: writer, text: edited });
+                        const saved = await driver.proxy.saveModelDocument({ uri, clientId: writer, model: model.text, baseVersion: 'any' });
+                        assert.ok(!edit.expect(saved.model?.root), 'edit.expect holds of the valid text, so this check cannot tell the edit apart');
+                        const reader = await openAs(driver, uri, 'conformance-reader');
+                        await driver.proxy.updateModelDocument({ uri, clientId: writer, model: edited, baseVersion: 'any' });
+                        // Not the last close: the reader still shows the writer's
+                        // text. Read at once, so a head that reverts after answering
+                        // could still pass this half.
+                        await driver.proxy.closeSession({ clientId: writer });
+                        const held = await driver.proxy.getModelDocument({ uri });
+                        assert.ok(edit.expect(held.model?.root), `closing one of two sessions dropped the unsaved text of ${uri}`);
+                        await driver.proxy.closeSession({ clientId: reader });
+                        await readUntil(driver, uri, document => document?.model !== undefined && !edit.expect(document.model.root), `${uri} did not go back to the text its save wrote after its last close`);
+                    }
+                    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: `updateModelDocuments writes a set all or none ${tag}`,
+            skipReason: edit && dependent
+                ? undefined
+                : dependent
+                    ? editSkipReason
+                    : 'fixture supplies no `dependent`, the second document a set needs besides `valid`',
+            body: edit && dependent
+                ? async () => {
+                    const driver = await connect();
+                    try {
+                        const model = resolveModel(valid);
+                        const other = resolveModel(dependent);
+                        await seed(driver, model);
+                        await seed(driver, other);
+                        const clientId = await startSession(driver, 'conformance-session');
+                        const { model: first } = TransferDocument.assertLoaded(await driver.proxy.openModelDocument({ uri: model.uri, clientId }));
+                        const { model: second } = TransferDocument.assertLoaded(await driver.proxy.openModelDocument({ uri: other.uri, clientId }));
+                        const edited = resolveDeferred(edit.to);
+                        // The stale member comes LAST, so a head that checks and
+                        // applies one document at a time has applied the first.
+                        const stale = await rejectionOf(driver.proxy.updateModelDocuments({
+                            clientId,
+                            updates: [
+                                { uri: model.uri, model: edited, baseVersion: first.version },
+                                { uri: other.uri, model: other.text, baseVersion: asModelVersion(second.version + 1) }
+                            ]
+                        }));
+                        assert.ok(isConflictError(stale), `a set with a stale member was not refused: ${String(stale)}`);
+                        const untouched = await driver.proxy.getModelDocument({ uri: model.uri });
+                        assert.strictEqual(untouched.model?.version, first.version, 'a refused set applied its first document');
+                        await driver.proxy.updateModelDocuments({
+                            clientId,
+                            updates: [
+                                { uri: model.uri, model: edited, baseVersion: first.version },
+                                { uri: other.uri, model: other.text, baseVersion: second.version }
+                            ]
+                        });
+                        const applied = await driver.proxy.getModelDocument({ uri: model.uri });
+                        assert.ok(edit.expect(applied.model?.root), 'edit.expect(root) was false — a current set was not applied');
+                        await driver.proxy.closeSession({ clientId });
+                    }
+                    finally {
+                        driver.dispose();
+                    }
+                }
+                : undefined
+        });
+        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 seed(driver, model);
+                        await seed(driver, other);
+                        // 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 author = await openAs(driver, model.uri);
+                        const before = driver.builds.length;
+                        await driver.proxy.updateModelDocument({
+                            uri: model.uri,
+                            clientId: author,
+                            model: resolveDeferred(edit.to),
+                            baseVersion: 'any'
+                        });
+                        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
+        });
+        const breakingEdit = language.breakingEdit;
+        checks.push({
+            title: `an edit that changes a watched dependent credits the dependent's event to no client ${tag}`,
+            skipReason: !dependent
+                ? cascadeSkipReason
+                : breakingEdit === undefined
+                    ? 'fixture supplies no `breakingEdit` (a text for `valid` that changes what `dependent` shows)'
+                    : undefined,
+            body: dependent && breakingEdit !== undefined
+                ? async () => {
+                    const driver = await connect();
+                    try {
+                        const model = resolveModel(valid);
+                        const other = resolveModel(dependent);
+                        const eventsFor = (uri, from = 0) => driver.events.slice(from).filter(event => event.document.uri === uri);
+                        await seed(driver, model);
+                        // The dependent's seeder keeps it open: an open document is
+                        // the one a head could wrongly credit to its opener.
+                        await seed(driver, other);
+                        // Watched after the seeds: a seed that changes nothing, over
+                        // a fixture file that holds its text already, sends a watcher
+                        // nothing to wait for.
+                        await driver.proxy.watchModelDocument({ uri: model.uri, clientId: SUBSCRIBER });
+                        await driver.proxy.watchModelDocument({ uri: other.uri, clientId: SUBSCRIBER });
+                        const author = await openAs(driver, model.uri);
+                        const before = driver.events.length;
+                        const answer = await driver.proxy.updateModelDocument({
+                            uri: model.uri,
+                            clientId: author,
+                            model: resolveDeferred(breakingEdit),
+                            baseVersion: 'any'
+                        });
+                        const written = () => eventsFor(model.uri, before).find(event => event.document.model?.version === answer.model?.version);
+                        await waitFor(() => written() !== undefined && eventsFor(other.uri, before).length > 0, {
+                            message: `no onDocumentUpdated event for both ${model.uri} and its dependent ${other.uri} after the breaking edit`
+                        });
+                        assert.deepStrictEqual({ reason: written()?.reason, sourceClientId: written()?.sourceClientId }, { reason: 'changed', sourceClientId: author }, 'the written document’s event is not the author’s change');
+                        // A recipient drops an event naming its own id as its echo, so
+                        // a dependent's event credited to the author, or to the client
+                        // that has the dependent open, is lost to exactly the client
+                        // that would show it.
+                        for (const event of eventsFor(other.uri, before)) {
+                            assert.deepStrictEqual({ reason: event.reason, sourceClientId: event.sourceClientId }, { reason: 'rebuilt', sourceClientId: UNKNOWN_CLIENT_ID }, 'the dependent’s event is not a rebuild that names no client');
+                        }
                     }
                     finally {
                         driver.dispose();
@@ -196,20 +902,35 @@ export function buildDataChecks(options) {
                     const driver = await connect();
                     try {
                         const model = resolveModel(valid);
-                        await driver.proxy.updateModelDocument({ uri: model.uri, clientId: SEEDER, model: model.text });
+                        // The seeder's write comes BEFORE any subscription, under an id
+                        // distinct from the author's so an event it caused 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 = await seed(driver, model);
+                        const author = await openAs(driver, model.uri);
                         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), {
+                        await driver.proxy.updateModelDocument({
+                            uri: model.uri,
+                            clientId: author,
+                            model: resolveDeferred(edit.to),
+                            baseVersion: 'any'
+                        });
+                        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);
+                        assert.strictEqual(last.sourceClientId, author);
+                        // The first delivery of the author's version is a change;
+                        // reported as rebuilt, it says the event echoes no write.
+                        assert.strictEqual(last.reason, 'changed');
                         // 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');
+                        assert.ok(!driver.events.some(event => event.sourceClientId === seeder), 'an onDocumentUpdated event arrived for the update made BEFORE watchModelDocument');
                     }
                     finally {
                         driver.dispose();