@hydranium/protocol 1.0.0-next.187 → 1.0.0-next.189

package/lib/transfer-document.d.ts

@@ -8,66 +8,73 @@
  ********************************************************************************/
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
-import { type SnapshotVersion } from './model-service/based-on';
+import { type ModelVersion, type TextVersion } from './model-service/base-version';
+/** The model a data server built for a document, encoded for the wire. */
+export interface TransferModelSnapshot<TRoot extends TransferElement, TDiagnostic = TransferDiagnostic> {
+    root: TRoot;
+    /** Absent until the document is validated; `[]` once it is and nothing was found. */
+    diagnostics?: TDiagnostic[];
+    /**
+     * The version of the text `root` was parsed from. A caller that mutates the
+     * model sends this back as the `baseVersion` of its write, and the server
+     * rejects the write with `ConflictError` once its text has moved past it.
+     */
+    version: ModelVersion;
+    /**
+     * The data server's fingerprint of `root` and `diagnostics`, or under its
+     * `'text-diagnostics'` strategy of the text `root` was parsed from and
+     * `diagnostics`.
+     * Independent of `version`; an equal hash also means equally validated.
+     */
+    hash: string;
+}
+/** The text a data server held for a document when it sent it. */
+export interface TextState {
+    /**
+     * The server's version of that text. A `TransferModelSnapshot.version` below it
+     * means the model was parsed from older text, and an update at this version
+     * or a later one follows.
+     */
+    version: TextVersion;
+    /**
+     * What `textHash` makes of the text alone: equal texts hash equal whatever
+     * their version or dirty state, across a revert or a server restart that
+     * numbers versions afresh.
+     */
+    hash: string;
+    /**
+     * Whether the text differs from the file, as the server last knew the file.
+     * A later change arrives as `onDocumentDirtyChanged` to a client watching
+     * the document.
+     */
+    dirty: boolean;
+}
 /**
  * Wire envelope exchanged between the model-server's data-server head and
- * its clients. Carries a transfer-shaped root — never an AST root — plus
- * the document's diagnostics in the adopter's wire-diagnostic shape.
+ * its clients: the server's model of a document and the text it holds for it,
+ * each absent where the server has none.
  *
  * The constraint `TTransfer extends TransferElement` pins the type system
  * to the wire data shape (no `$container` cycles, references as strings;
- * see {@link TransferElement}). The paired server-internal envelope is
- * `AstDocument<TAst extends AstNode, TDiagnostic>` in
- * `@hydranium/core` — same structural shape, different generic
- * constraint, used at the AST layer before the `TransferEncoder`
- * translation produces a {@link TransferDocument}.
+ * see {@link TransferElement}).
  */
 export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> {
     uri: string;
     /**
-     * The document version this snapshot was taken at — sourced from the
-     * server's text-document version counter. A caller that mutates the document
-     * subsequently sends this straight back as `TransferUpdateDocumentArgs.basedOn`, and
-     * the server rejects a stale-based update with `ConflictError`.
-     *
-     * See `@hydranium/protocol#errors` for the conflict-detection contract.
-     */
-    version: SnapshotVersion;
-    /**
-     * Absent when the document does not exist — the server answers an unknown URI
-     * with a shaped envelope rather than an error, so absence is an ordinary
-     * branch and not a catch. Declared required it reads as a guarantee, and
-     * every `root.x` compiles into a throw.
-     */
-    root?: TTransfer;
-    diagnostics: TDiagnostic[];
-    /**
-     * Whether the server holds text for this document that its file does not,
-     * as the server last knew the file: set on every document a data server
-     * answers or sends that the server holds, and absent otherwise. A change
-     * after this snapshot arrives as `onDocumentDirtyChanged` to a client
-     * watching the document.
-     */
-    dirty?: boolean;
-    /**
-     * What `textHash` makes of the text the server holds for this document
-     * when it sends it: set on every document a data server answers or sends
-     * that the server holds, and absent otherwise. Equal texts hash equal,
-     * whatever the version, so a client compares the text two snapshots hold,
-     * across a revert or a server restart that numbers versions afresh.
-     *
-     * Of the text alone. The data server's de-duplication fingerprint hashes the
-     * text or the transfer root together with the diagnostics, and changes with
-     * a diagnostic where this does not.
+     * Absent when the document does not exist: the server answers an unknown
+     * URI with a shaped envelope rather than an error, so absence is an
+     * ordinary branch and not a catch.
      */
-    textHash?: string;
+    model?: TransferModelSnapshot<TTransfer, TDiagnostic>;
+    /** Absent when the server holds no text for the document. */
+    text?: TextState;
 }
 /**
- * A {@link TransferDocument} the server actually had, so `root` is present.
+ * A {@link TransferDocument} the server actually had, so `model` is present.
  * Narrowed to by {@link TransferDocument.isLoaded} / {@link TransferDocument.assertLoaded}.
  */
 export type LoadedTransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> = TransferDocument<TTransfer, TDiagnostic> & {
-    root: TTransfer;
+    model: TransferModelSnapshot<TTransfer, TDiagnostic>;
 };
 export declare namespace TransferDocument {
     /**
@@ -76,27 +83,18 @@ export declare namespace TransferDocument {
      */
     function isLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(document: TransferDocument<TTransfer, TDiagnostic>): document is LoadedTransferDocument<TTransfer, TDiagnostic>;
     /**
-     * The same document with `root` no longer optional, or a throw. For call
+     * The same document with `model` no longer optional, or a throw. For call
      * sites where absence is a bug rather than a branch; the whole envelope is
-     * returned because a caller needing `root` usually needs `uri` or `version`
+     * returned because a caller needing `model` usually needs `uri` or `text`
      * with it.
      */
     function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(document: TransferDocument<TTransfer, TDiagnostic>): LoadedTransferDocument<TTransfer, TDiagnostic>;
+    /** The envelope for a document the server does not have. */
+    function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string): TransferDocument<TTransfer, TDiagnostic>;
     /**
-     * The envelope for a document the server does not have — `root` absent, and
-     * the version a read of a URI the store never saw reports.
-     *
-     * Exists so the absent branch is built the same way the present one is: both
-     * doors mark the version as coming from a read, and neither asks a caller to
-     * do it.
-     */
-    function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string, diagnostics?: TDiagnostic[]): TransferDocument<TTransfer, TDiagnostic>;
-    /**
-     * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
-     * to `[]` so test fixtures, fake protocol implementations, and the
-     * "no diagnostics yet" code paths don't need to repeat the empty array
-     * at every call site.
+     * Construct a {@link TransferDocument} envelope with a model, its version
+     * marked as coming from a read. `diagnostics` absent means not validated.
      */
-    function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string, version: number, root: TTransfer, diagnostics?: TDiagnostic[]): TransferDocument<TTransfer, TDiagnostic>;
+    function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string, version: number, root: TTransfer, hash: string, diagnostics?: TDiagnostic[], text?: TextState): TransferDocument<TTransfer, TDiagnostic>;
 }
 //# sourceMappingURL=transfer-document.d.ts.map

package/lib/transfer-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,OAAO,EAAE,eAAe,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,IAAI,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED;;;;;;;OAOG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;CACH"}
+{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEnG,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IACnG,IAAI,EAAE,KAAK,CAAC;IACZ,qFAAqF;IACrF,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACvB;;;;OAIG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACtD,6DAA6D;IAC7D,IAAI,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,KAAK,EAAE,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;CACvD,CAAC;AAEF,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED,4DAA4D;IAC5D,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,GACX,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;IAED;;;OAGG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,WAAW,EAAE,EAC3B,IAAI,CAAC,EAAE,SAAS,GAChB,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAM1C;CACH"}

package/lib/transfer-document.js

@@ -9,7 +9,7 @@
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransferDocument = void 0;
-const based_on_1 = require("./model-service/based-on");
+const base_version_1 = require("./model-service/base-version");
 var TransferDocument;
 (function (TransferDocument) {
     /**
@@ -17,13 +17,13 @@ var TransferDocument;
      * ordinary state — a view bound to a file that may not exist yet.
      */
     function isLoaded(document) {
-        return document.root !== undefined;
+        return document.model !== undefined;
     }
     TransferDocument.isLoaded = isLoaded;
     /**
-     * The same document with `root` no longer optional, or a throw. For call
+     * The same document with `model` no longer optional, or a throw. For call
      * sites where absence is a bug rather than a branch; the whole envelope is
-     * returned because a caller needing `root` usually needs `uri` or `version`
+     * returned because a caller needing `model` usually needs `uri` or `text`
      * with it.
      */
     function assertLoaded(document) {
@@ -33,26 +33,21 @@ var TransferDocument;
         return document;
     }
     TransferDocument.assertLoaded = assertLoaded;
-    /**
-     * The envelope for a document the server does not have — `root` absent, and
-     * the version a read of a URI the store never saw reports.
-     *
-     * Exists so the absent branch is built the same way the present one is: both
-     * doors mark the version as coming from a read, and neither asks a caller to
-     * do it.
-     */
-    function absent(uri, diagnostics = []) {
-        return { uri, version: (0, based_on_1.asSnapshotVersion)(0), root: undefined, diagnostics };
+    /** The envelope for a document the server does not have. */
+    function absent(uri) {
+        return { uri };
     }
     TransferDocument.absent = absent;
     /**
-     * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
-     * to `[]` so test fixtures, fake protocol implementations, and the
-     * "no diagnostics yet" code paths don't need to repeat the empty array
-     * at every call site.
+     * Construct a {@link TransferDocument} envelope with a model, its version
+     * marked as coming from a read. `diagnostics` absent means not validated.
      */
-    function create(uri, version, root, diagnostics = []) {
-        return { uri, version: (0, based_on_1.asSnapshotVersion)(version), root, diagnostics };
+    function create(uri, version, root, hash, diagnostics, text) {
+        return {
+            uri,
+            model: { root, version: (0, base_version_1.asModelVersion)(version), hash, ...(diagnostics === undefined ? {} : { diagnostics }) },
+            ...(text === undefined ? {} : { text })
+        };
     }
     TransferDocument.create = create;
 })(TransferDocument || (exports.TransferDocument = TransferDocument = {}));

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.187",
+  "version": "1.0.0-next.189",
   "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-protocol-methods.ts

@@ -60,7 +60,7 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
    'findReferenceCandidates',
    'resolveReference',
    'findNextName'
-] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
+] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol & string>;
 
 /** Notification-method names on {@link DocumentClientProtocol}. */
 export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [