@hydranium/protocol 1.0.0-next.185 → 1.0.0-next.188

package/lib/transfer-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,uDAAmF;AAmEnF,IAAiB,gBAAgB,CAuDhC;AAvDD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;IACtC,CAAC;IAJe,iBAAA,QAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,iBAAA,YAAY,eAO3B,CAAA;IAED;;;;;;;OAOG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,WAAW,GAAkB,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAA,4BAAiB,EAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAC/E,CAAC;IALe,iBAAA,MAAM,SAKrB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,WAAW,GAAkB,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAA,4BAAiB,EAAC,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IAPe,iBAAA,MAAM,SAOrB,CAAA;AACJ,CAAC,EAvDgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAuDhC"}
+{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,+DAAmG;AA4EnG,IAAiB,gBAAgB,CAmDhC;AAnDD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC;IACvC,CAAC;IAJe,iBAAA,QAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,iBAAA,YAAY,eAO3B,CAAA;IAED,4DAA4D;IAC5D,SAAgB,MAAM,CACnB,GAAW;QAEX,OAAO,EAAE,GAAG,EAAE,CAAC;IAClB,CAAC;IAJe,iBAAA,MAAM,SAIrB,CAAA;IAED;;;OAGG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,IAAY,EACZ,WAA2B,EAC3B,IAAgB;QAEhB,OAAO;YACJ,GAAG;YACH,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAA,6BAAc,EAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;YAC9G,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;SACzC,CAAC;IACL,CAAC;IAbe,iBAAA,MAAM,SAarB,CAAA;AACJ,CAAC,EAnDgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAmDhC"}

package/lib/util.d.ts

@@ -146,7 +146,7 @@ export declare function unreachable(input: never): never;
 export declare function getAt<T = unknown>(obj: unknown, path: string[]): T | undefined;
 /**
  * A stable, non-cryptographic digest of `text`, equal on every host for equal
- * text: the `TransferDocument.textHash` a data server stamps, so a client can
+ * text: the `TextState.hash` a data server stamps, so a client can
  * hash text of its own to compare. An array is read as its elements joined, so
  * a large text is hashed in parts without concatenating it. It tells whether a
  * text changed, not who could forge one.

package/lib/util.js

@@ -211,7 +211,7 @@ function getAt(obj, path) {
 }
 /**
  * A stable, non-cryptographic digest of `text`, equal on every host for equal
- * text: the `TransferDocument.textHash` a data server stamps, so a client can
+ * text: the `TextState.hash` a data server stamps, so a client can
  * hash text of its own to compare. An array is read as its elements joined, so
  * a large text is hashed in parts without concatenating it. It tells whether a
  * text changed, not who could forge one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.185",
+  "version": "1.0.0-next.188",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",

package/src/client/data-connection.ts

@@ -172,7 +172,7 @@ export class DataConnection<
             connected: () => this.connected(),
             reportError: (error, reported) => this.reportError(error, reported),
             restoreDirty: event => {
-               if (this.dirtyStates.get(event.uri) !== event.dirty) {
+               if (this.dirtyStates.get(event.uri) !== (event.text?.dirty ?? false)) {
                   this.deliverDirty(event);
                }
             },
@@ -234,7 +234,7 @@ export class DataConnection<
 
    /** Record `event` in {@link dirtyStates} and hand it to the client. */
    protected deliverDirty(event: TransferDocumentDirtyChangedEvent): void {
-      this.dirtyStates.set(event.uri, event.dirty);
+      this.dirtyStates.set(event.uri, event.text?.dirty ?? false);
       const client = this.client as unknown as Partial<Pick<DataClientProtocol<TTransfer>, 'onDocumentDirtyChanged'>>;
       client.onDocumentDirtyChanged?.(event);
    }

package/src/client/data-port.ts

@@ -27,7 +27,7 @@ import type { RpcConnectionLifecycle } from './rpc-connection';
  * `DataServerProtocol` surface, so wrapping it would re-derive the framework's
  * pass-throughs in a second place and lose the `as const satisfies keyof`
  * method allowlists, which cannot drift. Everything a form or a tree actually
- * does — the wire contract, the open/watch/update/close sequence, `basedOn`
+ * does — the wire contract, the open/watch/update/close sequence, `baseVersion`
  * conflict handling, echo filtering by `sourceClientId` — is host-invariant and
  * lives above this interface. What varies between hosts is exactly the
  * members below.

package/src/client/data-session.ts

@@ -11,12 +11,12 @@ import { type Disposable, Emitter, type Event } from 'vscode-jsonrpc';
 import { type Clock, SystemClock } from '../clock';
 import type { DataServerProtocol, DiagnosticOf, TransferDocumentDirtyChangedEvent, TransferDocumentUpdatedEvent } from '../data';
 import { isConflictError, SessionClosedError } from '../errors';
-import { type BasedOn, isSnapshotVersion, type SnapshotVersion } from '../model-service/based-on';
+import { type BaseVersion, isModelVersion, type ModelVersion, UNRECORDED_VERSION } from '../model-service/base-version';
 import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
 import type { OpenModelArgs } from '../model-server';
 import type { MaybePromise } from '../util';
 import type { RpcProxy } from '../rpc';
-import type { TransferDocument } from '../transfer-document';
+import type { TextState, TransferDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
 
 /**
@@ -29,6 +29,12 @@ export const DATA_SESSION_RESTORE_FAILED = defineMessage(
    'Could not restore {uri} after reconnecting to the data server: {detail}'
 );
 
+/** A write or open of `{uri}` that the data server answered without a model. */
+export const DATA_SESSION_ANSWER_WITHOUT_MODEL = defineMessage(
+   'hydranium/protocol/data-session-answer-without-model',
+   'The data server answered a write of {uri} without a model; the session counts that answer as older than every version.'
+);
+
 /**
  * A session re-opened documents after its connection dropped and cannot put
  * back what it wrote to them since their last save: another client changed
@@ -110,14 +116,18 @@ export interface DataSessionUnsavedWrite<
    TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
 > {
    /**
-    * The {@link TransferDocument.textHash} of the text the first of these
-    * writes was based on. `undefined` when the session could not tell, for a
-    * write based on `'anything'` or on a version it could not read back, and
-    * such a write is never sent again: the session cannot tell another
-    * client's text from the text it wrote over.
+    * The `text.hash` of the text the first of these writes was based on.
+    * `undefined` when the session could not tell, for a write based on
+    * `'any'` or on a version it could not read back, and such a write is
+    * never sent again: the session cannot tell another client's text from the
+    * text it wrote over.
     */
    readonly baseHash: string | undefined;
-   readonly answer: Pick<DataSessionDocument<TTransfer, TServer>, 'version' | 'textHash'>;
+   /**
+    * The model version the last of these writes was answered with, which
+    * orders its answers, and the `text.hash` of that answer.
+    */
+   readonly answer: { readonly version: ModelVersion; readonly hash?: string };
    /**
     * The call that made the last write, and for an `updateDocuments` call this
     * URI's index in it. Records whose `updates` is the same object were
@@ -251,18 +261,18 @@ export class DataSession<
    /** Per URI written since its last save, what {@link restore} needs to write it again. */
    protected readonly unsavedWrites = new Map<string, DataSessionUnsavedWrite<TTransfer, TServer>>();
    /**
-    * Per URI this session has open, the version and text hash of the last
-    * document one of its own calls was answered with, which spares the read a
-    * first unsaved write otherwise makes for its base; see {@link baseHashOf}.
+    * Per URI this session has open, the text of the last document one of its
+    * own calls was answered with, which spares the read a first unsaved write
+    * otherwise makes for its base; see {@link baseHashOf}.
     */
-   protected readonly lastAnswers = new Map<string, Pick<DataSessionDocument<TTransfer, TServer>, 'version' | 'textHash'>>();
+   protected readonly lastAnswers = new Map<string, TextState>();
    /**
-    * Per URI this session has open, the version its last save of it was
+    * Per URI this session has open, the model version its last save of it was
     * answered with; see {@link recordWrite}. Only a save sets it: an open
     * answers at the version of a write still in flight as well, and that
     * write is not saved.
     */
-   protected readonly savedVersions = new Map<string, SnapshotVersion>();
+   protected readonly savedVersions = new Map<string, ModelVersion>();
    /** Per URI, this session's calls still in flight on it, which a close waits for. */
    protected readonly inFlight = new Map<string, Set<Promise<unknown>>>();
    /** This session's saves still in flight, which a host's exit waits for; see {@link hasSavesInFlight}. */
@@ -347,8 +357,8 @@ export class DataSession<
     * view misreads as a concurrent third-party write, losing whatever the user
     * had typed.
     *
-    * Note that the returned snapshot's empty `diagnostics` does not mean
-    * valid: `open` settles at the integrity landmark, not at validation.
+    * Note that the returned snapshot's model usually has no `diagnostics`:
+    * `open` settles at the integrity landmark, not at validation.
     * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
     * from `getModelDocument({ includeDiagnostics: true })`.
     */
@@ -389,7 +399,7 @@ export class DataSession<
       }
       this.openUris.add(uri);
       this.serverUris.set(uri, document.uri);
-      this.lastAnswers.set(uri, { version: document.version, textHash: document.textHash });
+      this.recordText(uri, document);
       // Keyed as the server keys its notifications, which may not be how the
       // caller spelled the URI.
       this.host.forgetDirty?.(document.uri);
@@ -444,7 +454,7 @@ export class DataSession<
       return this.track([args.uri], async () => {
          const server = await this.connected();
          const update = { ...args };
-         const baseHash = await this.baseHashOf(server, args.uri, args.basedOn);
+         const baseHash = await this.baseHashOf(server, args.uri, args.baseVersion);
          const document = await server.updateModelDocument({ ...args, clientId: this.clientId });
          this.recordWrite(args.uri, document, baseHash, { update });
          return document;
@@ -464,7 +474,7 @@ export class DataSession<
             // records together.
             const updates = { ...args, updates: args.updates.map(update => ({ ...update })) };
             const server = await this.connected();
-            const baseHashes = await Promise.all(args.updates.map(update => this.baseHashOf(server, update.uri, update.basedOn)));
+            const baseHashes = await Promise.all(args.updates.map(update => this.baseHashOf(server, update.uri, update.baseVersion)));
             const documents = await server.updateModelDocuments({ ...args, clientId: this.clientId });
             args.updates.forEach((update, index) => this.recordWrite(update.uri, documents[index], baseHashes[index], { updates, index }));
             return documents;
@@ -483,11 +493,12 @@ export class DataSession<
          if (this.unsavedWrites.get(args.uri) === unsaved) {
             this.unsavedWrites.delete(args.uri);
          }
-         this.lastAnswers.set(args.uri, { version: document.version, textHash: document.textHash });
+         const answer = this.answerOf(args.uri, document);
+         this.recordText(args.uri, document);
          // The higher of two saves' answers, which may arrive out of order.
          const saved = this.savedVersions.get(args.uri);
-         if (saved === undefined || document.version > saved) {
-            this.savedVersions.set(args.uri, document.version);
+         if (saved === undefined || answer.version > saved) {
+            this.savedVersions.set(args.uri, answer.version);
          }
          return document;
       });
@@ -620,7 +631,7 @@ export class DataSession<
     * can still be reported lost that way.
     */
    protected forgetSavedWrite(event: TransferDocumentDirtyChangedEvent): void {
-      if (event.dirty) {
+      if (event.text?.dirty) {
          return;
       }
       // The flip names the server's key, which is not always the caller's
@@ -675,7 +686,7 @@ export class DataSession<
     * what it wrote since their last save where the re-open lost it, and tell
     * the host which of them lost it for good.
     *
-    * Decided per document by the re-opened {@link TransferDocument.textHash},
+    * Decided per document by the re-opened document's `text.hash`,
     * in {@link restoreOutcome}. Versions cannot decide a write: a revert moves
     * the version on and a restarted server numbers afresh, so the version the
     * last write was answered with never matches where a write is needed, and
@@ -717,7 +728,7 @@ export class DataSession<
             await server.watchModelDocument({ uri, clientId: this.clientId });
             if (this.openUris.has(uri)) {
                this.serverUris.set(uri, document.uri);
-               this.lastAnswers.set(uri, { version: document.version, textHash: document.textHash });
+               this.recordText(uri, document);
             }
             reopened.set(uri, document);
          } catch (error: unknown) {
@@ -742,12 +753,12 @@ export class DataSession<
          if (!this.openUris.has(uri)) {
             continue;
          }
-         // A failed read leaves the client's dirty state as it was; the
-         // document is restored all the same.
+         // A failed read, or one without text, leaves the client's dirty
+         // state as it was; the document is restored all the same.
          const current = await server.getModelDocument({ uri }).catch(() => undefined);
-         if (current?.dirty !== undefined) {
+         if (current?.text !== undefined) {
             try {
-               this.host.restoreDirty?.({ uri: current.uri, dirty: current.dirty });
+               this.host.restoreDirty?.({ uri: current.uri, text: current.text });
             } catch {
                // The client's listener failed, not the restore: the server
                // has the document open and watched, so it stays restored.
@@ -765,20 +776,21 @@ export class DataSession<
     * `write` (`'kept'`), holds the text the write started from, so the write
     * can be sent again (`'resend'`), or holds something else (`'lost'`).
     *
-    * A document without a text hash comes from a server that sends none, and
-    * counts as kept only at the version the write was answered with.
+    * A document without `text` comes from a server that sends none, and
+    * counts as kept only at the version the write was answered with. One
+    * without a model has no version to send the write again on.
     */
    protected restoreOutcome(
       write: DataSessionUnsavedWrite<TTransfer, TServer>,
       document: DataSessionDocument<TTransfer, TServer>
    ): 'kept' | 'resend' | 'lost' {
-      if (document.textHash === undefined) {
-         return document.version === write.answer.version ? 'kept' : 'lost';
+      if (document.text === undefined) {
+         return document.model?.version === write.answer.version ? 'kept' : 'lost';
       }
-      if (document.textHash === write.answer.textHash) {
+      if (document.text.hash === write.answer.hash) {
          return 'kept';
       }
-      return write.baseHash !== undefined && document.textHash === write.baseHash ? 'resend' : 'lost';
+      return document.model && write.baseHash !== undefined && document.text.hash === write.baseHash ? 'resend' : 'lost';
    }
 
    /**
@@ -808,7 +820,7 @@ export class DataSession<
       // on from the re-opened version, not from the one the record holds.
       for (const { uri, write, document, outcome } of outcomes) {
          if (outcome === 'kept' && document) {
-            this.unsavedWrites.set(uri, { ...write, answer: { version: document.version, textHash: document.textHash } });
+            this.unsavedWrites.set(uri, { ...write, answer: this.answerOf(uri, document) });
          }
       }
       // A document that could not be re-opened is forgotten, and was reported
@@ -823,7 +835,7 @@ export class DataSession<
       // In the order of the call's updates, which is the order of its answers.
       const resend = outcomes
          .flatMap(({ uri, write, document, outcome }) =>
-            outcome === 'resend' && document ? [{ uri, write, basedOn: document.version }] : []
+            outcome === 'resend' && document?.model ? [{ uri, write, baseVersion: document.model.version }] : []
          )
          .sort((left, right) => indexOf(left.write) - indexOf(right.write));
       if (resend.length === 0) {
@@ -833,15 +845,15 @@ export class DataSession<
       try {
          const { call } = resend[0].write;
          if ('update' in call) {
-            documents = [await server.updateModelDocument({ ...call.update, basedOn: resend[0].basedOn, clientId: this.clientId })];
+            documents = [await server.updateModelDocument({ ...call.update, baseVersion: resend[0].baseVersion, clientId: this.clientId })];
          } else {
-            const basedOn = new Map(resend.map(member => [indexOf(member.write), member.basedOn]));
+            const baseVersion = new Map(resend.map(member => [indexOf(member.write), member.baseVersion]));
             documents = await server.updateModelDocuments({
                ...call.updates,
                clientId: this.clientId,
                updates: call.updates.updates.flatMap((update, index) => {
-                  const version = basedOn.get(index);
-                  return version === undefined ? [] : [{ ...update, basedOn: version }];
+                  const version = baseVersion.get(index);
+                  return version === undefined ? [] : [{ ...update, baseVersion: version }];
                })
             });
          }
@@ -849,13 +861,13 @@ export class DataSession<
          if (isConflictError(error)) {
             return lose();
          }
-         for (const { uri, write, basedOn } of resend) {
+         for (const { uri, write, baseVersion } of resend) {
             this.host.reportError?.(error, resolve(DATA_SESSION_RESTORE_FAILED, { uri, detail: describeError(error) }));
             // Kept for the next restore, and numbered from the re-opened
             // version, as the kept records are: a record numbered by a server
             // that has since restarted would have later answers ignored.
             if (current(uri, write)) {
-               this.unsavedWrites.set(uri, { ...write, answer: { ...write.answer, version: basedOn } });
+               this.unsavedWrites.set(uri, { ...write, answer: { ...write.answer, version: baseVersion } });
             }
          }
          return [];
@@ -872,7 +884,7 @@ export class DataSession<
    }
 
    /**
-    * The text hash of the version `basedOn` names for `uri`, for a write that
+    * The text hash of the version `baseVersion` names for `uri`, for a write that
     * starts the URI's record in {@link unsavedWrites}; `undefined` for any
     * other write, whose record keeps the base it has.
     *
@@ -881,16 +893,16 @@ export class DataSession<
     * changes only with its version, so the text at a version is the text the
     * write, once it passes the gate, was applied to.
     */
-   protected async baseHashOf(server: RpcProxy<TServer>, uri: string, basedOn: BasedOn): Promise<string | undefined> {
-      if (this.unsavedWrites.has(uri) || !isSnapshotVersion(basedOn)) {
+   protected async baseHashOf(server: RpcProxy<TServer>, uri: string, baseVersion: BaseVersion): Promise<string | undefined> {
+      if (this.unsavedWrites.has(uri) || !isModelVersion(baseVersion)) {
          return undefined;
       }
       const known = this.lastAnswers.get(uri);
-      if (known?.version === basedOn) {
-         return known.textHash;
+      if (known?.version === baseVersion) {
+         return known.hash;
       }
       const read = await server.getModelDocument({ uri }).catch(() => undefined);
-      return read?.version === basedOn ? read.textHash : undefined;
+      return read?.text?.version === baseVersion ? read.text.hash : undefined;
    }
 
    /**
@@ -910,7 +922,7 @@ export class DataSession<
       baseHash: string | undefined,
       call: DataSessionUnsavedWrite<TTransfer, TServer>['call']
    ): void {
-      const answer = { version: document.version, textHash: document.textHash };
+      const answer = this.answerOf(uri, document);
       const kept = this.unsavedWrites.get(uri);
       if (kept && answer.version < kept.answer.version) {
          return;
@@ -920,7 +932,33 @@ export class DataSession<
          return;
       }
       this.unsavedWrites.set(uri, { baseHash: kept ? kept.baseHash : baseHash, answer, call });
-      this.lastAnswers.set(uri, answer);
+      this.recordText(uri, document);
+   }
+
+   /**
+    * What {@link DataSessionUnsavedWrite.answer} keeps of `document`. Every write
+    * and open answers with a model; one without is reported and counted older
+    * than every version, so it never replaces a real answer.
+    */
+   protected answerOf(
+      uri: string,
+      document: DataSessionDocument<TTransfer, TServer>
+   ): DataSessionUnsavedWrite<TTransfer, TServer>['answer'] {
+      if (!document.model) {
+         const reported = resolve(DATA_SESSION_ANSWER_WITHOUT_MODEL, { uri });
+         this.host.reportError?.(new Error(reported.text), reported);
+         return { version: UNRECORDED_VERSION, hash: document.text?.hash };
+      }
+      return { version: document.model.version, hash: document.text?.hash };
+   }
+
+   /** Keep `document`'s text in {@link lastAnswers}, or forget it for a server that sends none. */
+   protected recordText(uri: string, document: DataSessionDocument<TTransfer, TServer>): void {
+      if (document.text) {
+         this.lastAnswers.set(uri, document.text);
+      } else {
+         this.lastAnswers.delete(uri);
+      }
    }
 
    /** Run `call`, counted as in flight on each of `uris` until it settles. */

package/src/data/data-server-protocol.ts

@@ -100,10 +100,8 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
     * as every document request here does. The document is read from disk
     * unless a client has it open already, so the request carries no
     * `languageId`, `version` or `text` seed. Returns the document at
-    * the server's configured target phase — the same shape
-    * {@link getModelDocument} returns, except that `version` is taken from the
-    * text-document store so the caller's first `basedOn` write cannot
-    * self-conflict. A repeat open changes nothing.
+    * the server's configured target phase, as {@link getModelDocument} does.
+    * A repeat open changes nothing.
     *
     * Pair with {@link watchModelDocument} to receive subsequent build-phase
     * events (open returns a one-shot snapshot; later validation diagnostics

package/src/data/events.ts

@@ -10,7 +10,7 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TextState, TransferDocument } from '../transfer-document';
 
 /**
  * Why an update event fired. Subscribers filter on reason for behaviour
@@ -106,14 +106,20 @@ export type TransferDocumentSavedListener<
 /**
  * Delivered on the data-server when a watched document's text starts or stops
  * differing from its file, as the server last knew the file. The current
- * answer rides on every transfer document the server sends as `dirty`; this
- * carries only its changes, so a client that follows it needs no rebuild to
- * learn of a save.
+ * answer rides on every transfer document the server sends as `text.dirty`;
+ * this carries only its changes, so a client that follows it needs no rebuild
+ * to learn of a save.
  */
 export interface TransferDocumentDirtyChangedEvent {
    /** Canonical URI, keyed as the subscription is. */
    readonly uri: string;
-   readonly dirty: boolean;
+   /**
+    * The text the answer was decided on. It is sent before that text is
+    * built, so a `text.version` ahead of the model a client holds means an
+    * update at this version or a later one follows. Absent when the document
+    * no longer exists, or when the build that follows its release failed.
+    */
+   readonly text?: TextState;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */

package/src/data/requests.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { BasedOn } from '../model-service/based-on';
+import type { BaseVersion } from '../model-service/base-version';
 
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
@@ -53,16 +53,16 @@ export interface TransferUpdateDocumentArgs<TTransfer> {
    /** The whole structured model root, or its serialised textual form. */
    model: TTransfer | string;
    /**
-    * What this write was authored against. A `SnapshotVersion` is compared
+    * What this write was authored against. A `ModelVersion` is compared
     * against the server's current text-document version for `uri` and throws
-    * `ConflictError` on mismatch; `'anything'` writes unconditionally.
+    * `ConflictError` on mismatch; `'any'` writes unconditionally.
     *
     * **Required so that an ungated write is a decision rather than an
     * omission.** An optional gate is indistinguishable from a forgotten one at
     * the call site, and a file of twenty writes hides the one that lost the
     * field. Nothing else here can see that, since the defect is an absence.
     */
-   basedOn: BasedOn;
+   baseVersion: BaseVersion;
 }
 
 /** Update a document the session `clientId` has open, then persist it to disk. */