@hydranium/protocol 1.0.0-next.29 → 1.0.0-next.299

package/lib/patch-merge.js

@@ -13,31 +13,32 @@ exports.augmentWithTestOps = augmentWithTestOps;
 exports.reconcileByPatchReplay = reconcileByPatchReplay;
 const fast_json_patch_1 = require("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.
  */
-function augmentWithTestOps(baseline, userPatch) {
+function augmentWithTestOps(base, userPatch) {
     const augmented = [];
     for (const op of userPatch) {
         if (op.op === 'replace' || op.op === 'remove') {
-            augmented.push({ op: 'test', path: op.path, value: (0, fast_json_patch_1.getValueByPointer)(baseline, op.path) });
+            augmented.push({ op: 'test', path: op.path, value: (0, fast_json_patch_1.getValueByPointer)(base, op.path) });
         }
         augmented.push(op);
     }
@@ -45,36 +46,181 @@ function augmentWithTestOps(baseline, userPatch) {
 }
 /**
  * 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
- *   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.
- * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
- *   write and surfaces `fresh`.
+ * - `already-applied` — the refetch already holds the user's value at every
+ *   path the user changed, and the user's whole array for a path through
+ *   one; nothing is replayed.
+ * - `merged` — the foreign writer touched only paths the user did not, or
+ *   made the user's change itself at a path through no array; the merged
+ *   root carries both intents.
+ * - `conflict` — a same-path divergence tripped a `test` op, including the
+ *   user's own value inside an array the refetch holds otherwise than the
+ *   user; or an `add` collides with one the foreign writer made; or the
+ *   foreign writer removed or replaced what the user edited inside. The
+ *   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.
  */
-async function reconcileByPatchReplay(baseline, attempted, refetch) {
-    const userPatch = (0, fast_json_patch_1.compare)(baseline, attempted);
+async function reconcileByPatchReplay(base, ours, refetch) {
+    const userPatch = (0, fast_json_patch_1.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' };
     }
+    const comparable = toJson(theirs);
+    const pending = withoutAgreed(base, ours, comparable, userPatch);
+    if (pending.length === 0) {
+        return { status: 'already-applied', theirs };
+    }
+    if (addsCollide(base, comparable, pending)) {
+        return { status: 'conflict', theirs };
+    }
     try {
-        const merged = (0, fast_json_patch_1.applyPatch)((0, fast_json_patch_1.deepClone)(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+        const merged = (0, fast_json_patch_1.applyPatch)((0, fast_json_patch_1.deepClone)(theirs), augmentWithTestOps(base, pending), true).newDocument;
         return { status: 'merged', merged };
     }
     catch {
-        return { status: 'conflict', fresh };
+        return { status: 'conflict', theirs };
+    }
+}
+/**
+ * `userPatch` without the ops `theirs` already agrees with: a `replace` or
+ * object-key `add` whose key the object at its parent path holds at the
+ * user's value, a `remove` whose key that object lacks. A parent that is
+ * absent or no object agrees with nothing: a foreign writer deleted or
+ * replaced what the user edited inside, or a refetch omitted a document it
+ * could not read.
+ *
+ * Ops address array elements by index, so an op through an array agrees only
+ * when that array, the outermost on its path, equals the user's: matching one
+ * index of an array that shifted would drop the user's edit to another
+ * element. An insert never agrees, as {@link addsCollide} keeps two equal
+ * additions apart, and neither does any op through its array, or replaying
+ * the insert alone would add its element a second time. Each array is
+ * compared once, however many ops run through it and however many arrays the
+ * patch inserts into, so a bulk edit stays linear.
+ *
+ * `theirs` is the refetch through {@link toJson}.
+ */
+function withoutAgreed(base, ours, theirs, userPatch) {
+    const jsonOurs = toJson(ours);
+    // An insert is keyed by the outermost array on its path, as every op is looked up, so one set answers for every array.
+    const insertedArrays = new Set(userPatch
+        .filter(op => op.op === 'add' && Array.isArray(valueAt(base, op.path.slice(0, op.path.lastIndexOf('/')))))
+        .map(op => outermostArrayOn(jsonOurs, op.path)));
+    const arrayAgrees = new Map();
+    return userPatch.filter(op => {
+        const array = outermostArrayOn(jsonOurs, op.path);
+        if (array !== undefined) {
+            let agrees = arrayAgrees.get(array);
+            if (agrees === undefined) {
+                agrees = !insertedArrays.has(array) && (0, fast_json_patch_1._areEquals)(valueAt(theirs, array), valueAt(jsonOurs, array));
+                arrayAgrees.set(array, agrees);
+            }
+            return !agrees;
+        }
+        const cut = op.path.lastIndexOf('/');
+        const parent = valueAt(theirs, op.path.slice(0, cut));
+        if (typeof parent !== 'object' || parent === null || Array.isArray(parent)) {
+            return true;
+        }
+        const key = (0, fast_json_patch_1.unescapePathComponent)(op.path.slice(cut + 1));
+        if (op.op === 'remove') {
+            return Object.hasOwn(parent, key);
+        }
+        if (op.op !== 'replace' && op.op !== 'add') {
+            return true;
+        }
+        return !Object.hasOwn(parent, key) || !(0, fast_json_patch_1._areEquals)(Reflect.get(parent, key), op.value);
+    });
+}
+/** The outermost array a step of `pointer` before its last runs through in `document`, as a pointer; `undefined` for none. */
+function outermostArrayOn(document, pointer) {
+    const steps = pointer.split('/');
+    for (let i = 1; i < steps.length; i++) {
+        const prefix = steps.slice(0, i).join('/');
+        if (Array.isArray(valueAt(document, prefix))) {
+            return prefix;
+        }
+    }
+    return undefined;
+}
+/**
+ * `value` through JSON, as `compare` clones the values it diffs: an
+ * undefined-valued key would otherwise make two equal values differ.
+ */
+function toJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * 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, at
+ * another value once `withoutAgreed` has dropped the equal ones.
+ *
+ * Replayed, the first inserts the value a second time and the second replaces
+ * the foreign value. Identical array elements conflict rather than being
+ * skipped: skipping drops one of two insertions that merely happen to be
+ * equal. `theirs` is the refetch through {@link toJson}.
+ */
+function addsCollide(base, theirs, userPatch) {
+    // Each array's elements are counted once, however many ops insert into it, so a bulk insert stays linear.
+    const tallies = new Map();
+    return userPatch.some(op => {
+        if (op.op !== 'add') {
+            return false;
+        }
+        const cut = op.path.lastIndexOf('/');
+        const parent = op.path.slice(0, cut);
+        const before = valueAt(base, parent);
+        const now = valueAt(theirs, parent);
+        if (Array.isArray(before)) {
+            if (!Array.isArray(now)) {
+                return false;
+            }
+            let tally = tallies.get(parent);
+            if (!tally) {
+                tally = { before: tallyElements(before), now: tallyElements(now) };
+                tallies.set(parent, tally);
+            }
+            const key = canonicalJson(op.value);
+            return (tally.now.get(key) ?? 0) > (tally.before.get(key) ?? 0);
+        }
+        return typeof now === 'object' && now !== null && Object.hasOwn(now, (0, fast_json_patch_1.unescapePathComponent)(op.path.slice(cut + 1)));
+    });
+}
+/** How many elements of `array` there are of each value, keyed by {@link canonicalJson}. */
+function tallyElements(array) {
+    const tally = new Map();
+    for (const element of array) {
+        const key = canonicalJson(element);
+        tally.set(key, (tally.get(key) ?? 0) + 1);
+    }
+    return tally;
+}
+/** `value` as JSON with every object's keys sorted, so two deeply equal values give one string whatever their key order. */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, nested) => typeof nested === 'object' && nested !== null && !Array.isArray(nested)
+        ? Object.fromEntries(Object.entries(nested).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)))
+        : nested);
+}
+/** The value at `pointer`, or `undefined` when a step of it is missing. */
+function valueAt(document, pointer) {
+    try {
+        return (0, fast_json_patch_1.getValueByPointer)(document, pointer);
+    }
+    catch {
+        return undefined;
     }
 }
 /**
@@ -84,20 +230,20 @@ async function reconcileByPatchReplay(baseline, attempted, refetch) {
  * clobbered.
  */
 class ReconcilingConflictResolver {
-    resolve(baseline, attempted, refetch) {
-        return reconcileByPatchReplay(baseline, attempted, refetch);
+    resolve(base, ours, refetch) {
+        return reconcileByPatchReplay(base, ours, refetch);
     }
 }
 exports.ReconcilingConflictResolver = ReconcilingConflictResolver;
 /**
- * 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.
  */
 class ForceConflictResolver {
-    async resolve(_baseline, attempted, _refetch) {
-        return { status: 'merged', merged: attempted };
+    async resolve(_base, ours, _refetch) {
+        return { status: 'merged', merged: ours };
     }
 }
 exports.ForceConflictResolver = ForceConflictResolver;

package/lib/patch-merge.js.map

@@ -1 +1 @@
-{"version":3,"file":"patch-merge.js","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAyBlF,gDASC;AA+DD,wDAmBC;AAlHD,qDAA0H;AAE1H;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAAC,QAAgB,EAAE,SAA4C;IAC9F,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC7C,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAA,mCAAiB,EAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,SAAS,CAAC;AACpB,CAAC;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,sBAAsB,CACzC,QAAW,EACX,SAAY,EACZ,OAAqC;IAErC,MAAM,SAAS,GAAG,IAAA,yBAAO,EAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACpC,CAAC;IACD,IAAI,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,4BAAU,EAAC,IAAA,2BAAS,EAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC,WAAW,CAAC;QACvG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACN,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACxC,CAAC;AACJ,CAAC;AAmBD;;;;;GAKG;AACH,MAAa,2BAA2B;IACrC,OAAO,CAAmB,QAAW,EAAE,SAAY,EAAE,OAAqC;QACvF,OAAO,sBAAsB,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;CACH;AAJD,kEAIC;AAED;;;;;GAKG;AACH,MAAa,qBAAqB;IAC/B,KAAK,CAAC,OAAO,CAAmB,SAAY,EAAE,SAAY,EAAE,QAAsC;QAC/F,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;CACH;AAJD,sDAIC"}
+{"version":3,"file":"patch-merge.js","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":"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"}

package/lib/profile-session.d.ts

@@ -56,7 +56,12 @@ export interface ProfileSession {
     /** The same aggregate as structured records, for tests / programmatic use. */
     records(): readonly ProfileRecord[];
 }
-interface ScopeFrame {
+/**
+ * One in-flight {@link ProfileSession.scope} call. Held on the `protected`
+ * {@link DefaultProfileSession.stack} and named by
+ * {@link DefaultProfileSession.closeFrame}, so a subclass has to name it too.
+ */
+export interface ProfileScopeFrame {
     readonly id: string;
     /** Session-stopwatch reading when this scope began. */
     readonly start: number;
@@ -73,15 +78,14 @@ export declare class DefaultProfileSession implements ProfileSession {
     protected readonly identifier: string;
     /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
     protected readonly sessionStopwatch: Stopwatch;
-    protected readonly stack: ScopeFrame[];
+    protected readonly stack: ProfileScopeFrame[];
     protected readonly entries: Map<string, number[]>;
     constructor(logger: Logger, clock: Clock, identifier: string);
     scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
     scope<T>(id: string, fn: () => T): T;
     /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
-    protected closeFrame(frame: ScopeFrame): void;
+    protected closeFrame(frame: ProfileScopeFrame): void;
     records(): readonly ProfileRecord[];
     report(logLevel?: LogThreshold): void;
 }
-export {};
 //# sourceMappingURL=profile-session.d.ts.map

package/lib/profile-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile-session.d.ts","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAU,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,8EAA8E;IAC9E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAC;CACtC;AAED,UAAU,UAAU;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAOtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEjC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IARxC,6FAA6F;IAC7F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAM;IAC5C,SAAS,CAAC,QAAQ,CAAC,OAAO,wBAA+B;gBAGnC,MAAM,EAAE,MAAM,EACjC,KAAK,EAAE,KAAK,EACO,UAAU,EAAE,MAAM;IAKxC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IA2BpC,qFAAqF;IACrF,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgB7C,OAAO,IAAI,SAAS,aAAa,EAAE;IAUnC,MAAM,CAAC,QAAQ,GAAE,YAAsB,GAAG,IAAI;CAiBhD"}
+{"version":3,"file":"profile-session.d.ts","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAU,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,8EAA8E;IAC9E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAOtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEjC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IARxC,6FAA6F;IAC7F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAM;IACnD,SAAS,CAAC,QAAQ,CAAC,OAAO,wBAA+B;IAEzD,YACsB,MAAM,EAAE,MAAM,EACjC,KAAK,EAAE,KAAK,EACO,UAAU,EAAE,MAAM,EAGvC;IAED,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IA2BrC,qFAAqF;IACrF,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAcnD;IAED,OAAO,IAAI,SAAS,aAAa,EAAE,CAQlC;IAED,MAAM,CAAC,QAAQ,GAAE,YAAsB,GAAG,IAAI,CAgB7C;CACH"}

package/lib/profile-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile-session.js","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"profile-session.js","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"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"}

package/lib/project.d.ts

@@ -39,7 +39,10 @@
  * adopter-specific extension carried transparently through the typed
  * surface. The framework imposes no format on extension fields — they
  * ride on the JSON-RPC envelope as additional properties when crossing
- * the wire.
+ * the wire. A client receives a project's own enumerable fields as JSON: a
+ * getter or a method does not cross, and a class instance in a field arrives
+ * as a plain object, so the project type a client protocol declares holds the
+ * data fields alone.
  */
 export interface Project {
     /**

package/lib/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,OAAO;IACrB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,OAAO;IACrB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC"}

package/lib/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAgGlF;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAmGlF;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC"}

package/lib/random-uuid.d.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * A random v4 UUID. Not `crypto.randomUUID`: a browser offers it only in a
+ * secure context, and a client may be served over plain HTTP.
+ */
+export declare function randomUuid(): string;
+//# sourceMappingURL=random-uuid.d.ts.map

package/lib/random-uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-uuid.d.ts","sourceRoot":"","sources":["../src/random-uuid.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAOnC"}

package/lib/random-uuid.js

@@ -0,0 +1,24 @@
+"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 });
+exports.randomUuid = randomUuid;
+/**
+ * A random v4 UUID. Not `crypto.randomUUID`: a browser offers it only in a
+ * secure context, and a client may be served over plain HTTP.
+ */
+function randomUuid() {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    // Version 4, RFC 4122 variant.
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=random-uuid.js.map

package/lib/random-uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-uuid.js","sourceRoot":"","sources":["../src/random-uuid.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF;;;GAGG;AACH;IACG,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACpE,+BAA+B;IAC/B,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnF,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9G,CAAC"}

package/lib/reconcile-write.d.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * 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 } from './errors';
+import { type BaseVersion, type ModelVersion } from './model-service/base-version';
+import { type ConflictResolver } from './patch-merge';
+/** 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. `already-applied`: the refetch
+     * already held the edit, so nothing more was written. `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' | 'already-applied' | '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 declare function reconcileWrite<TModel extends object>(model: TModel, baseVersion: BaseVersion, hooks: ReconcileWriteHooks<TModel>): Promise<ReconcileWriteOutcome>;
+//# sourceMappingURL=reconcile-write.d.ts.map

package/lib/reconcile-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-write.d.ts","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,6FAA6F;AAC7F,MAAM,WAAW,cAAc,CAAC,MAAM;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACrC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACxC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACvD,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB;AAC9B,8BAA8B;AAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IACG;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;IACrG,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEP;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,SAAS,MAAM,EACvD,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAmChC"}

package/lib/reconcile-write.js

@@ -0,0 +1,69 @@
+"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 });
+exports.reconcileWrite = reconcileWrite;
+const errors_1 = require("./errors");
+const DEFAULT_MAX_WRITES = 3;
+/**
+ * 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.
+ */
+async function reconcileWrite(model, baseVersion, hooks) {
+    let candidate = model;
+    let candidateBaseVersion = baseVersion;
+    let previous;
+    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;
+        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 'already-applied':
+                return { status: 'already-applied', conflict, writes };
+            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(hooks, model, baseVersion) {
+    try {
+        await hooks.persist(model, baseVersion);
+        return undefined;
+    }
+    catch (err) {
+        if (!(0, errors_1.isConflictError)(err)) {
+            throw err;
+        }
+        return err;
+    }
+}
+//# sourceMappingURL=reconcile-write.js.map

package/lib/reconcile-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-write.js","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,qCAA+D;AAI/D,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAoD7B;;;;;GAKG;AACI,KAAK,yBACT,KAAa,EACb,WAAwB,EACxB,KAAkC;IAElC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,oBAAoB,GAAG,WAAW,CAAC;IACvC,IAAI,QAAmC,CAAC;IACxC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACxD,KAAK,IAAI,MAAM,GAAG,CAAC,GAAI,MAAM,EAAE,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAChG,CAAC;QACD,QAAQ,GAAG,QAAQ,CAAC;QACpB,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAClD,CAAC;QACD,IAAI,SAA6C,CAAC;QAClD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;YAChF,SAAS,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,SAAS,EAAE,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;YACtB,KAAK,QAAQ;gBACV,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;gBAC3B,oBAAoB,GAAG,SAAS,EAAE,WAAW,IAAI,KAAK,CAAC;gBACvD,SAAS;YACZ,KAAK,iBAAiB;gBACnB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YAC1D,KAAK,OAAO;gBACT,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACpD,KAAK,UAAU;gBACZ,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACnD,KAAK,aAAa;gBACf,MAAM,KAAK,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC7C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACzD,CAAC;IACJ,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,KAAK,UAAU,iBAAiB,CAC7B,KAAkC,EAClC,KAAa,EACb,WAAwB;IAExB,IAAI,CAAC;QACF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACxC,OAAO,SAAS,CAAC;IACpB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACrB,IAAI,CAAC,IAAA,wBAAe,EAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,GAAG,CAAC;QACb,CAAC;QACD,OAAO,GAAG,CAAC;IACd,CAAC;AACJ,CAAC"}

package/lib/rpc/bind-rpc-methods.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { MessageConnection } from 'vscode-jsonrpc';
+import { ResponseError, type MessageConnection } from 'vscode-jsonrpc';
 import type { LatencyCollector } from '../latency-collector';
 import { type Disposable } from '../util';
 /**
@@ -62,6 +62,30 @@ export interface BindRpcMethodsOptions {
      * Requests and notifications are both timed. Absent by default (no overhead).
      */
     readonly latency?: LatencyCollector;
+    /**
+     * Produce the `message` an outgoing rejection carries, so a user-facing
+     * error is rendered by the side that knows the reading user's language.
+     * Applied at this one chokepoint, which is what covers a caller's
+     * additional methods as well as the framework's own.
+     *
+     * Only a `ResponseError` is routed through it — a plain `Error` carries no
+     * identity to render from, and rewriting its message would relabel a
+     * developer-facing failure as a translated one. The rejection is
+     * RECONSTRUCTED rather than mutated, because the thrown value may be a
+     * shared constant; nothing is lost, since only `code`, `message` and `data`
+     * cross the wire and `instanceof` does not survive reconstruction anyway.
+     *
+     * Notifications are not covered, and "they have no reply channel" is only
+     * half the reason — a notification's own PAYLOAD can carry prose. What makes
+     * this sound is where that prose comes from: the only user-facing text on
+     * the data head's client surface is the diagnostics riding the
+     * document-updated and document-saved events, and those are read off
+     * `LangiumDocument.diagnostics`, which the document builder has already
+     * rendered at `Validated`. So they arrive rendered rather than escaping
+     * unrendered. A notification that ever carries prose of its OWN needs its
+     * own render at the raise site, as GLSP's actions do.
+     */
+    readonly renderErrorMessage?: (error: ResponseError<unknown>) => string;
 }
 /**
  * Register each named method on `target` as a handler on `connection`
@@ -82,8 +106,14 @@ export interface BindRpcMethodsOptions {
  *
  * Errors thrown synchronously from a request handler — or surfaced as a
  * rejected promise — propagate back to the caller through vscode-jsonrpc's
- * standard error envelope. Errors from a notification handler cannot, and are
- * routed to {@link BindRpcMethodsOptions.onNotificationError} instead.
+ * standard error envelope, its message rendered when
+ * {@link BindRpcMethodsOptions.renderErrorMessage} is supplied. A
+ * `ResponseError` from another copy of `vscode-jsonrpc` is rebuilt on this
+ * package's copy, so its code and data reach the caller when `connection` comes
+ * from that copy too, as the framework's own connections do; over a connection
+ * from another copy the caller receives a generic `InternalError`. Errors from a
+ * notification handler cannot propagate, and are routed to
+ * {@link BindRpcMethodsOptions.onNotificationError} instead.
  *
  * Accepts either a ready connection or a `Promise<MessageConnection>` —
  * registrations queue until the connection resolves, then attach. The

package/lib/rpc/bind-rpc-methods.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bind-rpc-methods.d.ts","sourceRoot":"","sources":["../../src/rpc/bind-rpc-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,SAAS,CAAC;AAIhE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC5C,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EAC1C,OAAO,GAAE,qBAA0B,GACnC,UAAU,CAmEZ"}
+{"version":3,"file":"bind-rpc-methods.d.ts","sourceRoot":"","sources":["../../src/rpc/bind-rpc-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,SAAS,CAAC;AAIhE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;CAC1E;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC5C,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EAC1C,OAAO,GAAE,qBAA0B,GACnC,UAAU,CA6EZ"}