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

package/src/transfer-document.ts

@@ -9,71 +9,80 @@
 
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
-import { asSnapshotVersion, type SnapshotVersion } from './model-service/based-on';
+import { asModelVersion, 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.
+    * 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.
     */
-   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.
-    */
-   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 namespace TransferDocument {
@@ -84,13 +93,13 @@ export namespace TransferDocument {
    export function isLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
       document: TransferDocument<TTransfer, TDiagnostic>
    ): document is LoadedTransferDocument<TTransfer, TDiagnostic> {
-      return document.root !== undefined;
+      return document.model !== undefined;
    }
 
    /**
-    * 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.
     */
    export function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
@@ -102,33 +111,29 @@ export namespace TransferDocument {
       return document;
    }
 
-   /**
-    * 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.
-    */
+   /** The envelope for a document the server does not have. */
    export function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
-      uri: string,
-      diagnostics: TDiagnostic[] = []
+      uri: string
    ): TransferDocument<TTransfer, TDiagnostic> {
-      return { uri, version: asSnapshotVersion(0), root: undefined, diagnostics };
+      return { uri };
    }
 
    /**
-    * 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.
     */
    export function create<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
       uri: string,
       version: number,
       root: TTransfer,
-      diagnostics: TDiagnostic[] = []
+      hash: string,
+      diagnostics?: TDiagnostic[],
+      text?: TextState
    ): TransferDocument<TTransfer, TDiagnostic> {
-      return { uri, version: asSnapshotVersion(version), root, diagnostics };
+      return {
+         uri,
+         model: { root, version: asModelVersion(version), hash, ...(diagnostics === undefined ? {} : { diagnostics }) },
+         ...(text === undefined ? {} : { text })
+      };
    }
 }

package/src/util.ts

@@ -251,7 +251,7 @@ export 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/model-service/based-on.d.ts

@@ -1,57 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-declare const snapshotMarker: unique symbol;
-/**
- * A text-document version that came out of a SNAPSHOT read: a document
- * envelope's `version`, which cannot move once the envelope exists.
- *
- * A plain number at runtime, usable anywhere a number is, and it travels the
- * wire as one. The marker exists only so the compiler can tell it apart from a
- * version read off a LIVE document, which is the same number type and is the
- * defect the conflict gate exists to prevent: read at write time it is whatever
- * the server is at now, which is the number the gate is about to compare it
- * against, so the gate passes unconditionally and a concurrent edit is
- * overwritten with nothing logged.
- */
-export type SnapshotVersion = number & {
-    readonly [snapshotMarker]: true;
-};
-/**
- * What a write declares it was based on: a version from a snapshot read, or
- * `'anything'`.
- *
- * `'anything'` is a precondition that always holds — the write accepts whatever
- * the server currently has, and therefore overwrites it. It is the honest
- * answer wherever the write was authored against no particular server version,
- * and a lie anywhere a reader handed the writer a document. The field carrying
- * it is required, so an ungated write is a word someone chose rather than a
- * field someone forgot.
- */
-export type BasedOn = SnapshotVersion | 'anything';
-/**
- * Whether `basedOn` names a version, and so arms the gate.
- *
- * Branch on this rather than on `basedOn !== 'anything'`, which reads as "not
- * based on anything" — the opposite of what the branch tests.
- */
-export declare function isSnapshotVersion(basedOn: BasedOn): basedOn is SnapshotVersion;
-/**
- * Mark a version as having come from a snapshot read.
- *
- * **For the envelope constructors, not for callers.** Every door that builds a
- * document envelope applies it on the way in, so anything a read returns
- * already carries it and a writer never needs this. A caller reaching for it is
- * asserting a provenance the compiler was about to deny — the read-late defect
- * written out where a reviewer can see it.
- */
-export declare function asSnapshotVersion(version: number): SnapshotVersion;
-/** A snapshot version no write can match, so a write based on it conflicts. */
-export declare const NO_MATCHING_VERSION: SnapshotVersion;
-export {};
-//# sourceMappingURL=based-on.d.ts.map

package/lib/model-service/based-on.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"based-on.d.ts","sourceRoot":"","sources":["../../src/model-service/based-on.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,GAAG,UAAU,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,eAAe,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAElE;AAED,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,EAAE,eAAuC,CAAC"}

package/lib/model-service/based-on.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"based-on.js","sourceRoot":"","sources":["../../src/model-service/based-on.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;AA+BlF;;;;;GAKG;AACH,2BAAkC,OAAgB;IAC/C,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,2BAAkC,OAAe;IAC9C,OAAO,OAA0B,CAAC;AACrC,CAAC;AAED,+EAA+E;AAClE,QAAA,mBAAmB,GAAoB,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/src/model-service/based-on.ts

@@ -1,63 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-
-declare const snapshotMarker: unique symbol;
-
-/**
- * A text-document version that came out of a SNAPSHOT read: a document
- * envelope's `version`, which cannot move once the envelope exists.
- *
- * A plain number at runtime, usable anywhere a number is, and it travels the
- * wire as one. The marker exists only so the compiler can tell it apart from a
- * version read off a LIVE document, which is the same number type and is the
- * defect the conflict gate exists to prevent: read at write time it is whatever
- * the server is at now, which is the number the gate is about to compare it
- * against, so the gate passes unconditionally and a concurrent edit is
- * overwritten with nothing logged.
- */
-export type SnapshotVersion = number & { readonly [snapshotMarker]: true };
-
-/**
- * What a write declares it was based on: a version from a snapshot read, or
- * `'anything'`.
- *
- * `'anything'` is a precondition that always holds — the write accepts whatever
- * the server currently has, and therefore overwrites it. It is the honest
- * answer wherever the write was authored against no particular server version,
- * and a lie anywhere a reader handed the writer a document. The field carrying
- * it is required, so an ungated write is a word someone chose rather than a
- * field someone forgot.
- */
-export type BasedOn = SnapshotVersion | 'anything';
-
-/**
- * Whether `basedOn` names a version, and so arms the gate.
- *
- * Branch on this rather than on `basedOn !== 'anything'`, which reads as "not
- * based on anything" — the opposite of what the branch tests.
- */
-export function isSnapshotVersion(basedOn: BasedOn): basedOn is SnapshotVersion {
-   return typeof basedOn === 'number';
-}
-
-/**
- * Mark a version as having come from a snapshot read.
- *
- * **For the envelope constructors, not for callers.** Every door that builds a
- * document envelope applies it on the way in, so anything a read returns
- * already carries it and a writer never needs this. A caller reaching for it is
- * asserting a provenance the compiler was about to deny — the read-late defect
- * written out where a reviewer can see it.
- */
-export function asSnapshotVersion(version: number): SnapshotVersion {
-   return version as SnapshotVersion;
-}
-
-/** A snapshot version no write can match, so a write based on it conflicts. */
-export const NO_MATCHING_VERSION: SnapshotVersion = asSnapshotVersion(-1);