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

package/src/errors.ts

@@ -9,6 +9,7 @@
 
 import { ResponseError } from 'vscode-jsonrpc';
 import { defineMessage, type HydraniumMessageData, messageData } from './messages/primitives';
+import { asModelVersion, type ModelVersion, type TextVersion } from './model-service/base-version';
 
 /*
  * Every error here is a typed error: a caller reacts to it, so it has a class,
@@ -32,8 +33,8 @@ import { defineMessage, type HydraniumMessageData, messageData } from './message
  * That tier only ever works untranslated, which is why it is the last resort
  * behind the numeric code rather than the primary check.
  */
-export const STALE_BASED_UPDATE = defineMessage(
-   'hydranium/protocol/stale-based-update',
+export const STALE_BASE_VERSION_UPDATE = defineMessage(
+   'hydranium/protocol/stale-base-version-update',
    'The edit to {uri} was not applied: it was made to an older version of the document.'
 );
 
@@ -69,35 +70,31 @@ export const HYDRANIUM_ERROR_CODES = {
  */
 export const CONFLICT_ERROR_CODE = HYDRANIUM_ERROR_CODES.conflict;
 
-/**
- * Structured payload carried in {@link ConflictError.data}, and the only place
- * a post-RPC caller can read the version mismatch from.
- */
+/** Structured payload carried in {@link ConflictError.data}. */
 export interface ConflictErrorData extends HydraniumMessageData {
    readonly uri: string;
-   /** The based-on version the caller authored against. */
-   readonly expectedVersion: number;
+   /** The base version the caller authored against. */
+   readonly baseVersion: ModelVersion;
    /** The server's current text-document version at the time of the throw. */
-   readonly actualVersion: number;
+   readonly actualVersion: TextVersion;
 }
 
 /**
  * Thrown by a client session's `update` / `save` when the caller-
- * supplied based-on version no longer matches the server's current text-
+ * supplied base version no longer matches the server's current text-
  * document version for the same URI — i.e. the snapshot the caller
  * authored against has been superseded by an intervening edit.
  *
  * Extends vscode-jsonrpc's {@link ResponseError} so the typed
  * {@link ConflictErrorData} payload rides on the standard JSON-RPC
  * error envelope (`code`, `message`, `data`) — all three fields are
- * preserved by RPC reconstruction. Adopters that catch the error on
- * the receiving side of an RPC call read the version mismatch from
- * `err.data` (the instance is reconstructed as a generic
- * `ResponseError`, so subclass getters / fields do not survive).
+ * preserved by RPC reconstruction. `createRpcProxy` revives it into
+ * this class on the receiving side; a path that does not leaves a
+ * plain `ResponseError`, readable through `err.data` only.
  *
- * Detection is driven by the required `basedOn` field of every write
- * request; a caller with no meaningful based-on version passes
- * `'anything'` and gets no gating.
+ * Detection is driven by the required `baseVersion` field of every write
+ * request; a caller with no meaningful base version passes
+ * `'any'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -111,22 +108,22 @@ export interface ConflictErrorData extends HydraniumMessageData {
  * No auto-retry or auto-merge ships by default.
  */
 export class ConflictError extends ResponseError<ConflictErrorData> {
-   constructor(uri: string, expectedVersion: number, actualVersion: number) {
+   constructor(uri: string, baseVersion: ModelVersion, actualVersion: TextVersion) {
       // The identity rides alongside the typed payload rather than replacing
       // it: `isConflictError`'s name check is surface an adopter may bind, so
       // adding the identity widens the payload rather than reshaping it.
-      super(CONFLICT_ERROR_CODE, STALE_BASED_UPDATE.format({ uri }), {
+      super(CONFLICT_ERROR_CODE, STALE_BASE_VERSION_UPDATE.format({ uri }), {
          uri,
-         expectedVersion,
+         baseVersion,
          actualVersion,
-         ...messageData(STALE_BASED_UPDATE, { uri })
+         ...messageData(STALE_BASE_VERSION_UPDATE, { uri })
       });
       this.name = 'ConflictError';
       // ResponseError's constructor calls `Object.setPrototypeOf(this,
       // ResponseError.prototype)` to keep its own prototype chain intact across
       // transpilation targets; that resets us to ResponseError, hiding the
       // ConflictError-specific getters. Restore the prototype here so
-      // `err.uri` / `.expectedVersion` / `.actualVersion` resolve through this
+      // `err.uri` / `.baseVersion` / `.actualVersion` resolve through this
       // class.
       Object.setPrototypeOf(this, ConflictError.prototype);
    }
@@ -136,19 +133,19 @@ export class ConflictError extends ResponseError<ConflictErrorData> {
    }
 
    /**
-    * The based-on version the caller authored against.
+    * The base version the caller authored against.
     *
     * Must not be renamed to `expected`, nor its sibling to `actual`: a test
     * reporter reads an error carrying both as an assertion failure, and
     * vitest's formatter then ASSIGNS to them, which throws on an accessor and
     * replaces the real failure with a `TypeError`.
     */
-   get expectedVersion(): number {
-      return this.data!.expectedVersion;
+   get baseVersion(): ModelVersion {
+      return this.data!.baseVersion;
    }
 
-   /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
-   get actualVersion(): number {
+   /** The server's version at the time of the throw. Not `actual` — see {@link baseVersion}. */
+   get actualVersion(): TextVersion {
       return this.data!.actualVersion;
    }
 }
@@ -299,9 +296,52 @@ export class ReservedClientIdError extends ResponseError<{ readonly clientId: st
    }
 }
 
+/**
+ * Rebuilds one typed error from the `data` that crossed the wire, or
+ * `undefined` when `data` lacks the fields the class reads.
+ */
+type ProtocolErrorReviver = (data: Readonly<Record<string, unknown>>) => ResponseError<unknown> | undefined;
+
+/** One entry per typed error class, keyed by its code; a class without one reaches a caller as a plain `ResponseError`. */
+const PROTOCOL_ERROR_REVIVERS: ReadonlyMap<number, ProtocolErrorReviver> = new Map<number, ProtocolErrorReviver>([
+   [
+      CONFLICT_ERROR_CODE,
+      ({ uri, baseVersion, actualVersion }) =>
+         typeof uri === 'string' && typeof baseVersion === 'number' && typeof actualVersion === 'number'
+            ? new ConflictError(uri, asModelVersion(baseVersion), actualVersion)
+            : undefined
+   ],
+   [SESSION_CLOSED_ERROR_CODE, ({ clientId }) => (typeof clientId === 'string' ? new SessionClosedError(clientId) : undefined)],
+   [
+      DOCUMENT_NOT_OPEN_ERROR_CODE,
+      ({ uri, clientId }) => (typeof uri === 'string' && typeof clientId === 'string' ? new DocumentNotOpenError(uri, clientId) : undefined)
+   ],
+   [DUPLICATE_CLIENT_ID_ERROR_CODE, ({ clientId }) => (typeof clientId === 'string' ? new DuplicateClientIdError(clientId) : undefined)],
+   [RESERVED_CLIENT_ID_ERROR_CODE, ({ clientId }) => (typeof clientId === 'string' ? new ReservedClientIdError(clientId) : undefined)]
+]);
+
+/**
+ * `error` as an instance of the typed error class its code names, with its
+ * message, data and stack kept, or `error` itself when its code names none or
+ * its data lacks the fields that class reads.
+ * An RPC reconstructs every rejection as a plain `ResponseError`, which has
+ * none of the class getters.
+ */
+export function reviveProtocolError(error: unknown): unknown {
+   if (!(error instanceof ResponseError) || error.data === null || typeof error.data !== 'object') {
+      return error;
+   }
+   const revived = PROTOCOL_ERROR_REVIVERS.get(error.code)?.(error.data);
+   if (!revived) {
+      return error;
+   }
+   return Object.assign(revived, { message: error.message, data: error.data, stack: error.stack });
+}
+
 /**
  * Whether `error` is a {@link SessionClosedError}: by name in-process, by code
- * after an RPC, where it arrives as a plain `ResponseError`.
+ * when it arrives as a plain `ResponseError`, through a path that does not
+ * {@link reviveProtocolError revive} it.
  */
 export function isSessionClosedError(error: unknown): error is SessionClosedError {
    return hasErrorIdentity(error, 'SessionClosedError', SESSION_CLOSED_ERROR_CODE);
@@ -340,12 +380,12 @@ const CONFLICT_ERROR_MESSAGE_MARKER = ': it was made to an older version of the
  *     canonical wire-side check; the JSON-RPC `code` field is preserved
  *     across reconstruction, so any adopter catching after an RPC call
  *     hits this branch.
- *  3. `error.message` contains the marker {@link STALE_BASED_UPDATE}'s
+ *  3. `error.message` contains the marker {@link STALE_BASE_VERSION_UPDATE}'s
  *     English carries — fallback for transports that re-wrap the message
  *     and drop the code (rare).
  *
- * `instanceof ConflictError` alone would silently return `false` on the
- * reconstructed shape, so callers do not use it.
+ * `instanceof ConflictError` alone returns `false` on a rejection that was
+ * not {@link reviveProtocolError revived}, so callers do not use it.
  */
 export function isConflictError(error: unknown): error is ConflictError {
    if (!(error instanceof Error)) {

package/src/index.ts

@@ -31,6 +31,7 @@ export * from './latency-collector';
 // the modules that raise them.
 export * from './messages/primitives';
 export * from './patch-merge';
+export * from './reconcile-write';
 export * from './noop-logger';
 export * from './observable-value';
 export * from './profile-session';

package/src/messages/index.ts

@@ -25,9 +25,9 @@
 
 export * from './primitives';
 
-export { DOCUMENT_NOT_OPEN, DUPLICATE_CLIENT_ID, SESSION_CLOSED, STALE_BASED_UPDATE } from '../errors';
+export { DOCUMENT_NOT_OPEN, DUPLICATE_CLIENT_ID, SESSION_CLOSED, STALE_BASE_VERSION_UPDATE } from '../errors';
 export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
-export { DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
+export { DATA_SESSION_ANSWER_WITHOUT_MODEL, DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
 export {
    RELAY_REPLAY_FAILED,
    RELAY_TRANSPORT_OPEN_FAILED,

package/src/model-service/base-version.ts

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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;
+
+/**
+ * The version of the text a model was parsed from: a snapshot of the store's
+ * {@link TextVersion}, not a counter of its own. A document envelope carries
+ * it, and it 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 ModelVersion = number & { readonly [snapshotMarker]: true };
+
+/**
+ * The store's version of a document's text, which moves with every change of it.
+ * Unbranded, so a write refuses it as `baseVersion`: it can name text newer than
+ * the caller's model, and a write based on it would pass the gate with older content.
+ */
+export type TextVersion = number;
+
+/**
+ * The version a write was authored against, from a snapshot read, or `'any'`: a
+ * precondition that always holds, so the write overwrites whatever the server has.
+ * `'any'` is a lie for a write authored against a document a read handed over.
+ */
+export type BaseVersion = ModelVersion | 'any';
+
+/** Whether `baseVersion` names a version, and so arms the gate. */
+export function isModelVersion(baseVersion: BaseVersion): baseVersion is ModelVersion {
+   return typeof baseVersion === '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 asModelVersion(version: number): ModelVersion {
+   return version as ModelVersion;
+}
+
+/**
+ * The model version of a root no document factory path built, so nothing
+ * records the text it came from. No write matches it, so a write based on it
+ * conflicts.
+ */
+export const UNRECORDED_VERSION: ModelVersion = asModelVersion(-2);
+
+/**
+ * The model version of a root parsed from text the store holds under no
+ * version: the file, read while the store held the document open with other
+ * text. Below every text version, so the model reads as behind and a write
+ * based on it conflicts.
+ */
+export const STALE_VERSION: ModelVersion = asModelVersion(-1);

package/src/model-service/index.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-// Generic payload types the data protocol shares with core: the based-on
+// Generic payload types the data protocol shares with core: the base
 // version, which the server's model service checks writes against, and the
 // reference candidates, which core's scope and completion code produce.
 
-export * from './based-on';
+export * from './base-version';
 export * from './reference-candidate';

package/src/patch-merge.ts

@@ -52,8 +52,9 @@ export function augmentWithTestOps(base: object, userPatch: ReadonlyArray<JsonPa
 
 /**
  * Outcome of {@link reconcileByPatchReplay}. The caller persists `merged` and
- * takes it as the new base, drops + surfaces the `theirs` root on `conflict`, and
- * decides its own fallback (e.g. force-retry) on `no-op` / `unavailable`.
+ * takes it as the new base, drops + surfaces the `theirs` root on `conflict`,
+ * catches up with the server on `no-op`, and decides its own fallback (e.g.
+ * force-retry) on `unavailable`.
  */
 export type ReconcileOutcome<T> =
    | {
@@ -68,9 +69,10 @@ export type ReconcileOutcome<T> =
      }
    | {
         /**
-         * The user's root already equalled the base, so the version gate
-         * fired on drift that changed nothing. No refetch was performed and
-         * there is nothing to persist — retrying the same write reproduces it.
+         * The user's root equalled the base, so the gate fired on another writer's
+         * change and the caller is behind the server (`ConflictError.actualVersion`).
+         * Nothing was refetched. Catch up from the update at that version or a later
+         * one, or refetch; forcing the write overwrites the other writer's change.
          */
         status: 'no-op';
      }
@@ -98,8 +100,8 @@ export type ReconcileOutcome<T> =
  * (`base → ours`), refetch the server's current root (theirs), and replay the
  * intent on top under strict, {@link augmentWithTestOps}-guarded `applyPatch`.
  *
- * - `no-op` — the user's root equals the base, so the gate fired on a
- *   benign version drift; nothing to replay (refetch is skipped).
+ * - `no-op` — the user's root equals the base: nothing to replay, and no
+ *   refetch; the caller's document is behind the server's.
  * - `unavailable` — the refetch produced nothing; caller falls back.
  * - `merged` — the foreign writer touched only paths the user did not; the
  *   merged root carries both intents.
@@ -187,8 +189,8 @@ export interface ConflictResolver {
    /**
     * Reconcile the user's `base → ours` intent against the current
     * server state (theirs, from `refetch`), returning a {@link ReconcileOutcome} the caller
-    * acts on (persist `merged`, drop on `conflict`, fall back on `no-op` /
-    * `unavailable`).
+    * acts on (persist `merged`, drop on `conflict`, catch up on `no-op`, fall
+    * back on `unavailable`).
     */
    resolve<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
 }

package/src/reconcile-write.ts

@@ -0,0 +1,124 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+import { type ConflictError, isConflictError } from './errors';
+import { type BaseVersion, type ModelVersion } from './model-service/base-version';
+import { type ConflictResolver } from './patch-merge';
+
+const DEFAULT_MAX_WRITES = 3;
+
+/** A model and the version of the text it was read from, which a write based on it names. */
+export interface VersionedModel<TModel> {
+   readonly model: TModel;
+   readonly baseVersion: ModelVersion;
+}
+
+/** The I/O and policy a {@link reconcileWrite} call needs. */
+export interface ReconcileWriteHooks<TModel> {
+   /**
+    * Write `model`. Called with the caller's own `baseVersion` first, with the
+    * refetch's on a merged write, and with `'any'` for a merge that refetched
+    * nothing, where the resolver has already decided to win.
+    */
+   persist(model: TModel, baseVersion: BaseVersion): Promise<void>;
+   /**
+    * Current server-side model, or `undefined` when unavailable. Its version is
+    * read in the tick its text is: a later one lets a merged write overwrite an
+    * edit the merge never saw.
+    */
+   refetch(): Promise<VersionedModel<TModel> | undefined>;
+   /** The last in-sync model the user's intent is measured against. */
+   readonly base: TModel;
+   readonly conflictResolver: ConflictResolver;
+   /** Writes, the first included, after which a still-conflicting edit is dropped; 3 when absent. */
+   readonly maxWrites?: number;
+   /** Runs when the refetch is unavailable; absent, the edit is left unwritten. */
+   onUnavailable?(model: TModel, conflict: ConflictError): Promise<void>;
+}
+
+/**
+ * What {@link reconcileWrite} did. Every status but `persisted` follows a
+ * conflict, and carries the last one and the writes made, the first included.
+ */
+export type ReconcileWriteOutcome =
+   /** The first write landed. */
+   | { readonly status: 'persisted' }
+   | {
+        /**
+         * `merged`: a merged write landed. `unchanged`: the edit was empty, so the
+         * caller is behind the server. `conflict`: the resolver found a same-path
+         * collision. `dropped`: the writes ran out. `unavailable`: the refetch
+         * produced nothing and {@link ReconcileWriteHooks.onUnavailable} ran.
+         */
+        readonly status: 'merged' | 'unchanged' | 'conflict' | 'dropped' | 'unavailable';
+        readonly conflict: ConflictError;
+        readonly writes: number;
+     };
+
+/**
+ * Persist `model`, and on a `ConflictError` reconcile the user's `base → model`
+ * intent onto the refetched server model and write the merge, gated on the
+ * refetch's version, again on each conflict up to `maxWrites` writes. A
+ * non-conflict error is re-thrown.
+ */
+export async function reconcileWrite<TModel extends object>(
+   model: TModel,
+   baseVersion: BaseVersion,
+   hooks: ReconcileWriteHooks<TModel>
+): Promise<ReconcileWriteOutcome> {
+   let candidate = model;
+   let candidateBaseVersion = baseVersion;
+   let previous: ConflictError | undefined;
+   const maxWrites = hooks.maxWrites ?? DEFAULT_MAX_WRITES;
+   for (let writes = 1; ; writes++) {
+      const conflict = await persistOrConflict(hooks, candidate, candidateBaseVersion);
+      if (!conflict) {
+         return previous ? { status: 'merged', conflict: previous, writes } : { status: 'persisted' };
+      }
+      previous = conflict;
+      if (writes >= maxWrites) {
+         return { status: 'dropped', conflict, writes };
+      }
+      let refetched: VersionedModel<TModel> | undefined;
+      const outcome = await hooks.conflictResolver.resolve(hooks.base, model, async () => {
+         refetched = await hooks.refetch();
+         return refetched?.model;
+      });
+      switch (outcome.status) {
+         case 'merged':
+            candidate = outcome.merged;
+            candidateBaseVersion = refetched?.baseVersion ?? 'any';
+            continue;
+         case 'no-op':
+            return { status: 'unchanged', conflict, writes };
+         case 'conflict':
+            return { status: 'conflict', conflict, writes };
+         case 'unavailable':
+            await hooks.onUnavailable?.(model, conflict);
+            return { status: 'unavailable', conflict, writes };
+      }
+   }
+}
+
+/** The `ConflictError` the write raised, or `undefined` when it landed. */
+async function persistOrConflict<TModel>(
+   hooks: ReconcileWriteHooks<TModel>,
+   model: TModel,
+   baseVersion: BaseVersion
+): Promise<ConflictError | undefined> {
+   try {
+      await hooks.persist(model, baseVersion);
+      return undefined;
+   } catch (err: unknown) {
+      if (!isConflictError(err)) {
+         throw err;
+      }
+      return err;
+   }
+}

package/src/rpc/create-rpc-proxy.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { Emitter, type Event, type MessageConnection } from 'vscode-jsonrpc';
+import { reviveProtocolError } from '../errors';
 import { type BindRpcMethodsOptions, bindRpcMethods } from './bind-rpc-methods';
 import { assertValidMethodNamespace } from './wire-prefix';
 
@@ -198,6 +199,9 @@ function assertSingleArg(wireName: string, args: unknown[]): void {
  * params, results and errors, and a second layer here would double every
  * traced line.
  *
+ * A rejection whose code names one of the framework's typed errors is rethrown
+ * as that class, through {@link reviveProtocolError}.
+ *
  * Accepts either a ready connection or a `Promise<MessageConnection>` —
  * proxy methods called before the promise resolves queue until it does,
  * then dispatch, so adopters can wire the proxy before its underlying
@@ -293,7 +297,8 @@ export function createRpcProxy<T extends object, TLocal extends object = never>(
             const capturedError = new Error(`RPC request '${wireName}' failed`);
             return resolvedConnection
                .then(connection => connection.sendRequest(wireName, args[0]))
-               .catch((err: unknown) => {
+               .catch((rejection: unknown) => {
+                  const err = reviveProtocolError(rejection);
                   if (err instanceof Error && capturedError.stack) {
                      err.stack = `${err.stack ?? err.message}\nCaused by request from:\n${capturedError.stack}`;
                   }