@hydranium/protocol 1.0.0-next.117 → 1.0.0-next.123

package/src/patch-merge.ts

@@ -7,34 +7,43 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { applyPatch, compare, deepClone, getValueByPointer, type Operation as JsonPatchOperation } from 'fast-json-patch';
+import {
+   _areEquals,
+   applyPatch,
+   compare,
+   deepClone,
+   getValueByPointer,
+   type Operation as JsonPatchOperation,
+   unescapePathComponent
+} from 'fast-json-patch';
 
 /**
- * Augment a user-intent JSON patch (computed `baseline → attempted`) with
+ * Augment a user-intent JSON patch (computed `base → ours`) with
  * `test` ops so a strict `applyPatch` against freshly-fetched server state
  * fails loudly when a foreign writer changed a path the user also changed.
  *
  * `fast-json-patch`'s `validateOperation: true` validates op structure and
  * path resolvability but NOT the pre-existing value — a plain `replace` /
  * `remove` silently overwrites whatever the foreign writer put there. For each
- * `replace` / `remove` op we prepend a `test` op carrying the baseline value at
+ * `replace` / `remove` op we prepend a `test` op carrying the base value at
  * that path, so a same-path divergence becomes a `TEST_OPERATION_FAILED` throw.
  * The caller treats that as a real field-level conflict (drop + refetch) rather
  * than silently clobbering the foreign edit.
  *
- * `add` ops are left unguarded: the path is new, so there is no baseline value
- * to test against, and add-vs-add overlaps are out of scope for this floor.
+ * `add` ops get no `test` op: the path is new, so there is no base value
+ * to test. {@link reconcileByPatchReplay} checks them against theirs
+ * instead; a caller applying this patch itself does not get that check.
  *
  * Used behind the framework's `ConflictError` contract by every reconcile
  * path — the GLSP recording command's undo/redo and forward-write, via
  * {@link ReconcilingConflictResolver}, and an adopter's form-widget save — so
  * they share one collision-detection rule.
  */
-export function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[] {
+export function augmentWithTestOps(base: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[] {
    const augmented: JsonPatchOperation[] = [];
    for (const op of userPatch) {
       if (op.op === 'replace' || op.op === 'remove') {
-         augmented.push({ op: 'test', path: op.path, value: getValueByPointer(baseline, op.path) });
+         augmented.push({ op: 'test', path: op.path, value: getValueByPointer(base, op.path) });
       }
       augmented.push(op);
    }
@@ -42,39 +51,38 @@ export function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<Js
 }
 
 /**
- * Outcome of {@link reconcileByPatchReplay}. The caller persists / re-baselines
- * on `merged`, drops + surfaces the `fresh` root on `conflict`, and decides its
- * own fallback (e.g. force-retry) on `no-op` / `unavailable`.
+ * 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`.
  */
 export type ReconcileOutcome<T> =
    | {
         /** The replay succeeded: the foreign writer touched no path the user did. */
         status: 'merged';
         /**
-         * A fresh root built on the refetched server state, carrying both
-         * intents. It is NOT the caller's `attempted` root — re-baseline on
-         * this value, or the next write diffs against state the server never
-         * had.
+         * A new root built on theirs, carrying both intents. It is NOT the
+         * caller's `ours` root — take this value as the new base, or the next
+         * write diffs against state the server never had.
          */
         merged: T;
      }
    | {
         /**
-         * The user's root already equalled the baseline, so the version gate
+         * 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.
          */
         status: 'no-op';
      }
    | {
-        /** A guarded `test` op tripped: user and foreign writer touched one path. */
+        /** User and foreign writer changed one path, or both added the same element or key. */
         status: 'conflict';
         /**
          * The server's current root, refetched and unmodified — the user's
          * intent was NOT applied to it. Surface it and drop the write; treating
          * it as a merge result silently discards what the user typed.
          */
-        fresh: T;
+        theirs: T;
      }
    | {
         /**
@@ -87,39 +95,84 @@ export type ReconcileOutcome<T> =
 
 /**
  * Shared three-way reconcile for a `ConflictError`: diff the user's intent
- * (`baseline → attempted`), refetch the server's current root, and replay the
+ * (`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 baseline, so the gate fired on a
+ * - `no-op` — the user's root equals the base, so the gate fired on a
  *   benign version drift; nothing to replay (refetch is skipped).
  * - `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.
- * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
- *   write and surfaces `fresh`.
+ * - `conflict` — a same-path divergence tripped a `test` op, or an `add`
+ *   collides with one the foreign writer made; caller drops the write and
+ *   surfaces `theirs`.
  *
  * I/O is the caller's: `refetch` supplies the current root, and applying the
- * `merged` result (update vs save, re-baseline, UI refresh) stays at the call
+ * `merged` result (update vs save, new base, UI refresh) stays at the call
  * site so form and GLSP paths keep their own persistence semantics.
  */
 export async function reconcileByPatchReplay<T extends object>(
-   baseline: T,
-   attempted: T,
+   base: T,
+   ours: T,
    refetch: () => Promise<T | undefined>
 ): Promise<ReconcileOutcome<T>> {
-   const userPatch = compare(baseline, attempted);
+   const userPatch = compare(base, ours);
    if (userPatch.length === 0) {
       return { status: 'no-op' };
    }
-   const fresh = await refetch();
-   if (!fresh) {
+   const theirs = await refetch();
+   if (!theirs) {
       return { status: 'unavailable' };
    }
+   if (addsCollide(base, theirs, userPatch)) {
+      return { status: 'conflict', theirs };
+   }
    try {
-      const merged = applyPatch(deepClone(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+      const merged = applyPatch(deepClone(theirs), augmentWithTestOps(base, userPatch), true).newDocument;
       return { status: 'merged', merged };
    } catch {
-      return { status: 'conflict', fresh };
+      return { status: 'conflict', theirs };
+   }
+}
+
+/**
+ * Whether an `add` of `userPatch` collides with one the foreign writer made:
+ * it inserts a value into an array that `theirs` holds more often than
+ * `base` did, or it adds an object key that `theirs` already holds.
+ *
+ * Replayed, the first inserts the value a second time and the second replaces
+ * the foreign value. Identical values conflict rather than being skipped:
+ * skipping drops one of two additions that merely happen to be equal.
+ */
+function addsCollide(base: object, theirs: object, userPatch: readonly JsonPatchOperation[]): boolean {
+   // Through JSON, as `compare` clones the add values: an undefined-valued key
+   // in `theirs` would otherwise make an equal element count as another.
+   const comparable = JSON.parse(JSON.stringify(theirs)) as object;
+   return userPatch.some(op => {
+      if (op.op !== 'add') {
+         return false;
+      }
+      const cut = op.path.lastIndexOf('/');
+      const before = valueAt(base, op.path.slice(0, cut));
+      const now = valueAt(comparable, op.path.slice(0, cut));
+      if (Array.isArray(before)) {
+         return Array.isArray(now) && occurrences(now, op.value) > occurrences(before, op.value);
+      }
+      return typeof now === 'object' && now !== null && Object.hasOwn(now, unescapePathComponent(op.path.slice(cut + 1)));
+   });
+}
+
+/** How many elements of `array` deeply equal `value`, whatever their key order. */
+function occurrences(array: readonly unknown[], value: unknown): number {
+   return array.filter(element => _areEquals(element, value)).length;
+}
+
+/** The value at `pointer`, or `undefined` when a step of it is missing. */
+function valueAt(document: object, pointer: string): unknown {
+   try {
+      return getValueByPointer(document, pointer);
+   } catch {
+      return undefined;
    }
 }
 
@@ -132,12 +185,12 @@ export async function reconcileByPatchReplay<T extends object>(
  */
 export interface ConflictResolver {
    /**
-    * Reconcile the user's `baseline → attempted` intent against the current
-    * server state (`refetch`), returning a {@link ReconcileOutcome} the caller
+    * 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`).
     */
-   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+   resolve<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
 }
 
 /**
@@ -147,19 +200,19 @@ export interface ConflictResolver {
  * clobbered.
  */
 export class ReconcilingConflictResolver implements ConflictResolver {
-   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
-      return reconcileByPatchReplay(baseline, attempted, refetch);
+   resolve<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return reconcileByPatchReplay(base, ours, refetch);
    }
 }
 
 /**
- * Last-writer-wins {@link ConflictResolver}: always reports the `attempted`
+ * Last-writer-wins {@link ConflictResolver}: always reports the `ours`
  * state as merged, without refetching or guarding. Suitable for single-client
  * tools or always-regenerated artifacts where a concurrent foreign edit may be
  * overwritten. A foreign edit to any field is clobbered.
  */
 export class ForceConflictResolver implements ConflictResolver {
-   async resolve<T extends object>(_baseline: T, attempted: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
-      return { status: 'merged', merged: attempted };
+   async resolve<T extends object>(_base: T, ours: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return { status: 'merged', merged: ours };
    }
 }

package/src/transfer-document.ts

@@ -29,9 +29,8 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
    /**
     * 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 `TransferUpdateArgs.basedOn` (or
-    * `TransferSaveArgs.basedOn`), and the server rejects a stale-based update
-    * with `ConflictError`.
+    * 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.
     */

package/lib/model-service/args.d.ts

@@ -1,65 +0,0 @@
-/********************************************************************************
- * 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
- ********************************************************************************/
-/**
- * Argument shapes for the in-process `ModelService` facade — the
- * canonical home for the lifecycle operation signatures. Implementation
- * lives in `@hydranium/core/langium/model-service`; this protocol
- * package owns the types so wire-side projections (the data-server
- * protocol in `./data`) can structurally extend them rather than
- * mirroring them by hand.
- *
- * `./model-server.ts` re-exports them, so an import from either path
- * resolves.
- */
-import type { BasedOn } from './based-on';
-/** Identifies a client-document binding. Every facade operation carries these fields. */
-export interface TransferClientArgs {
-    /** Document URI. */
-    uri: string;
-    /** Stable identifier for the client invoking the operation. */
-    clientId: string;
-}
-/**
- * Update a document's content via the in-process facade. `model` may be
- * the structured (transfer-model or AST) root or its serialised textual
- * form — implementations decide which is faster on their transport.
- * Generic over `T` so adopters parameterise the structured shape against
- * their grammar's transfer-model overlay; passing a string is always
- * allowed.
- */
-export interface TransferUpdateArgs<T> extends TransferClientArgs {
-    /** Structured model root or its serialised textual form. */
-    model: T | string;
-    /**
-     * What this update was authored against. A `SnapshotVersion` is compared
-     * against the server's current text-document version for `uri` and throws
-     * `ConflictError` on mismatch; `'anything'` 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;
-}
-/**
- * Persist a document to disk via the in-process facade. Same `model`
- * shape as {@link TransferUpdateArgs}.
- */
-export interface TransferSaveArgs<T> extends TransferClientArgs {
-    /** Structured model root or its serialised textual form. */
-    model: T | string;
-    /**
-     * Same semantics and same requirement as {@link TransferUpdateArgs.basedOn}.
-     * `save` delegates the gating check to its inner `update`, so this field
-     * threads through to the same `ConflictError` site.
-     */
-    basedOn: BasedOn;
-}
-//# sourceMappingURL=args.d.ts.map

package/lib/model-service/args.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/model-service/args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IAChC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC9D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,OAAO,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAC5D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CACnB"}

package/lib/model-service/args.js

@@ -1,11 +0,0 @@
-"use strict";
-/********************************************************************************
- * 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
- ********************************************************************************/
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=args.js.map

package/lib/model-service/args.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/model-service/args.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/src/model-service/args.ts

@@ -1,69 +0,0 @@
-/********************************************************************************
- * 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
- ********************************************************************************/
-
-/**
- * Argument shapes for the in-process `ModelService` facade — the
- * canonical home for the lifecycle operation signatures. Implementation
- * lives in `@hydranium/core/langium/model-service`; this protocol
- * package owns the types so wire-side projections (the data-server
- * protocol in `./data`) can structurally extend them rather than
- * mirroring them by hand.
- *
- * `./model-server.ts` re-exports them, so an import from either path
- * resolves.
- */
-
-import type { BasedOn } from './based-on';
-
-/** Identifies a client-document binding. Every facade operation carries these fields. */
-export interface TransferClientArgs {
-   /** Document URI. */
-   uri: string;
-   /** Stable identifier for the client invoking the operation. */
-   clientId: string;
-}
-
-/**
- * Update a document's content via the in-process facade. `model` may be
- * the structured (transfer-model or AST) root or its serialised textual
- * form — implementations decide which is faster on their transport.
- * Generic over `T` so adopters parameterise the structured shape against
- * their grammar's transfer-model overlay; passing a string is always
- * allowed.
- */
-export interface TransferUpdateArgs<T> extends TransferClientArgs {
-   /** Structured model root or its serialised textual form. */
-   model: T | string;
-   /**
-    * What this update was authored against. A `SnapshotVersion` is compared
-    * against the server's current text-document version for `uri` and throws
-    * `ConflictError` on mismatch; `'anything'` 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;
-}
-
-/**
- * Persist a document to disk via the in-process facade. Same `model`
- * shape as {@link TransferUpdateArgs}.
- */
-export interface TransferSaveArgs<T> extends TransferClientArgs {
-   /** Structured model root or its serialised textual form. */
-   model: T | string;
-   /**
-    * Same semantics and same requirement as {@link TransferUpdateArgs.basedOn}.
-    * `save` delegates the gating check to its inner `update`, so this field
-    * threads through to the same `ConflictError` site.
-    */
-   basedOn: BasedOn;
-}