@hydranium/protocol 1.0.0-next.25 → 1.0.0-next.251

package/lib/node/process-memory.js

@@ -0,0 +1,291 @@
+"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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatProcessMemory = formatProcessMemory;
+exports.snapshotFilePath = snapshotFilePath;
+exports.writeHeapSnapshotToDir = writeHeapSnapshotToDir;
+exports.formatPodMemory = formatPodMemory;
+/*
+ * Node-only process- and pod-level memory introspection plus heap-snapshot
+ * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
+ * `/proc`); the only host-specific part is naming the processes, which a head
+ * supplies through a `ProcessClassifier`.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const v8 = __importStar(require("node:v8"));
+const logger_1 = require("../logger");
+/**
+ * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
+ * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
+ * language-server process with document counts, see `formatServerState`.
+ */
+function formatProcessMemory(label) {
+    const mem = process.memoryUsage();
+    const heap = v8.getHeapStatistics();
+    const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+    return [
+        `${label}:`,
+        `  heap      ${logger_1.Format.bytes(mem.heapUsed)} used / ${logger_1.Format.bytes(mem.heapTotal)} total / ` +
+            `${logger_1.Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+        `  rss       ${logger_1.Format.bytes(mem.rss)}, external ${logger_1.Format.bytes(mem.external)}, arrayBuffers ${logger_1.Format.bytes(mem.arrayBuffers)}`,
+        `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
+    ].join('\n');
+}
+/**
+ * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
+ * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
+ * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
+ * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
+ * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
+ * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
+ * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
+ * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
+ * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
+ * by extension.
+ */
+function snapshotFilePath(directory, label, prefix, ext) {
+    const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
+    const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
+    const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
+    return path.join(dir, `${stem}.${ext}`);
+}
+/**
+ * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
+ * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
+ * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
+ * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
+ * {@link label} are folded into the name.
+ */
+function writeHeapSnapshotToDir(directory, label, prefix = 'server-heap') {
+    const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+    v8.writeHeapSnapshot(filePath);
+    return filePath;
+}
+const CGROUP_ROOT = '/sys/fs/cgroup';
+function readNumber(file) {
+    try {
+        const text = fs.readFileSync(file, 'utf8').trim();
+        if (text === 'max') {
+            return Number.POSITIVE_INFINITY;
+        }
+        const value = Number(text);
+        return Number.isFinite(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
+function readKeyedBytes(file) {
+    const out = {};
+    try {
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            const [key, value] = line.trim().split(/\s+/);
+            if (key && value !== undefined) {
+                const num = Number(value);
+                if (Number.isFinite(num)) {
+                    out[key] = num;
+                }
+            }
+        }
+    }
+    catch {
+        // file absent or unreadable; caller handles the empty map.
+    }
+    return out;
+}
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
+/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
+function readAllProcs() {
+    const procs = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync('/proc');
+    }
+    catch {
+        return procs;
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry)) {
+            continue;
+        }
+        let status = '';
+        try {
+            status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+        if (!rssMatch) {
+            continue;
+        }
+        const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
+        let label = '';
+        try {
+            label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+        }
+        catch {
+            // fall back to the process name from status below.
+        }
+        if (!label) {
+            label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
+        }
+        procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
+    }
+    return procs;
+}
+/**
+ * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
+ * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
+ * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
+ * all the pod's processes anyway.
+ */
+function collectProcessRss(rootPid) {
+    const all = readAllProcs();
+    let selected = all;
+    let scoped = false;
+    if (rootPid !== undefined) {
+        const childrenByPpid = new Map();
+        for (const proc of all) {
+            (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)).push(proc);
+        }
+        const tree = [];
+        const queue = all.filter(proc => proc.pid === rootPid);
+        while (queue.length > 0) {
+            const proc = queue.shift();
+            tree.push(proc);
+            queue.push(...(childrenByPpid.get(proc.pid) ?? []));
+        }
+        if (tree.length > 0) {
+            selected = tree;
+            scoped = true;
+        }
+    }
+    const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
+    selected.sort((a, b) => b.rssBytes - a.rssBytes);
+    return { total, processes: selected, scoped };
+}
+/**
+ * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
+ * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
+ * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
+ * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
+ * the per-process split is visible. Explains itself when no cgroup memory controller is present
+ * (e.g. local dev outside a container).
+ */
+function formatPodMemory(options = {}) {
+    const classify = options.classify ?? defaultProcessClassifier;
+    const appLabel = options.appLabel ?? 'Application';
+    const lines = ['Pod memory snapshot:'];
+    const v2Current = path.join(CGROUP_ROOT, 'memory.current');
+    const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
+    if (fs.existsSync(v2Current)) {
+        const current = readNumber(v2Current);
+        const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
+        const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
+        const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
+        lines.push('  cgroup    v2');
+        lines.push(`  current   ${current !== undefined ? logger_1.Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? logger_1.Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+        lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? logger_1.Format.bytes(max) : 'n/a'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown anon ${logger_1.Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${logger_1.Format.bytes(stat.file ?? 0)} (page cache), ` +
+                `kernel ${logger_1.Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${logger_1.Format.bytes(stat.sock ?? 0)}`);
+        }
+    }
+    else if (fs.existsSync(v1Usage)) {
+        const v1 = path.join(CGROUP_ROOT, 'memory');
+        const current = readNumber(v1Usage);
+        const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
+        const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
+        const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
+        lines.push('  cgroup    v1');
+        lines.push(`  current   ${current !== undefined ? logger_1.Format.bytes(current) : 'n/a'}`);
+        lines.push(`  peak      ${peak !== undefined ? logger_1.Format.bytes(peak) : 'n/a'}`);
+        // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
+        lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? logger_1.Format.bytes(limit) : 'unlimited'}`);
+        if (Object.keys(stat).length > 0) {
+            lines.push(`  breakdown rss ${logger_1.Format.bytes(stat.rss ?? 0)}, cache ${logger_1.Format.bytes(stat.cache ?? 0)} (page cache), ` +
+                `kernel ${logger_1.Format.bytes(stat.kernel ?? 0)}`);
+        }
+    }
+    else {
+        lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
+    }
+    // Root at this process so local dev reports only the app's tree, not the whole machine.
+    const { processes } = collectProcessRss(process.pid);
+    if (processes.length > 0) {
+        const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
+        const appProcs = classified.filter(proc => proc.isApp);
+        const otherProcs = classified.filter(proc => !proc.isApp);
+        const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+        lines.push('');
+        lines.push(`  ${appLabel}: ${logger_1.Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+        for (const proc of appProcs) {
+            lines.push(`    ${logger_1.Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+        }
+        const singletonCounts = new Map();
+        for (const proc of appProcs) {
+            if (proc.singletonExpected) {
+                singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
+            }
+        }
+        for (const [role, count] of singletonCounts) {
+            if (count > 1) {
+                lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
+            }
+        }
+        if (otherProcs.length > 0) {
+            const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
+            lines.push(`  Other (tooling/debugger, not counted above): ${logger_1.Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
+        }
+        lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
+        lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=process-memory.js.map

package/lib/node/process-memory.js.map

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

package/lib/noop-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"noop-logger.d.ts","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,cAAe,YAAW,MAAM;IAC7D,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAI1F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKpC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAI3C"}
+{"version":3,"file":"noop-logger.d.ts","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,cAAe,YAAW,MAAM;IAC7D,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAElG;IAEQ,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGnC;IAED,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGxC;CACH"}

package/lib/noop-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"noop-logger.js","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,uDAAmD;AAGnD;;;;;;;;GAQG;AACH,MAAa,UAAW,SAAQ,gCAAc;IACjC,IAAI,CAAC,MAAgB,EAAE,MAAc,EAAE,QAAgB,EAAE,KAAyB;QACzF,qCAAqC;IACxC,CAAC;IAEQ,OAAO,CAAC,IAAY;QAC1B,qEAAqE;QACrE,OAAO,IAAI,CAAC;IACf,CAAC;IAES,MAAM,CAAC,SAAiB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAA+C,CAAC;QACtE,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;CACH;AAdD,gCAcC"}
+{"version":3,"file":"noop-logger.js","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,uDAAmD;AAGnD;;;;;;;;GAQG;AACH,gBAAwB,SAAQ,gCAAc;IACjC,IAAI,CAAC,MAAgB,EAAE,MAAc,EAAE,QAAgB,EAAE,KAAyB;QACzF,qCAAqC;IACxC,CAAC;IAEQ,OAAO,CAAC,IAAY;QAC1B,qEAAqE;QACrE,OAAO,IAAI,CAAC;IACf,CAAC;IAES,MAAM,CAAC,SAAiB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAA+C,CAAC;QACtE,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;CACH"}

package/lib/observable-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"observable-value.js","sourceRoot":"","sources":["../src/observable-value.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAwDlF,8CAMC;AAjBD,MAAM,eAAe,GAAe,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;AAEhF,6EAA6E;AAC7E,MAAM,WAAW,GAAiB,GAAG,EAAE,CAAC,eAAe,CAAC;AAExD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAI,KAA8B;IAChE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,KAAoC,CAAC;IACvD,OAAO,OAAO,IAAI,SAAS,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU,CAAC;AAC3E,CAAC;AAED,IAAiB,eAAe,CAoB/B;AApBD,WAAiB,eAAe;IAC7B;;;;;OAKG;IACH,SAAgB,EAAE,CAAI,KAAQ;QAC3B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAuB,EAAE,CAAC;IACvD,CAAC;IAFe,kBAAE,KAEjB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,IAAI,CAAI,KAA8B;QACnD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAFe,oBAAI,OAEnB,CAAA;AACJ,CAAC,EApBgB,eAAe,+BAAf,eAAe,QAoB/B"}
+{"version":3,"file":"observable-value.js","sourceRoot":"","sources":["../src/observable-value.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;AA6ClF,MAAM,eAAe,GAAe,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;AAEhF,6EAA6E;AAC7E,MAAM,WAAW,GAAiB,GAAG,EAAE,CAAC,eAAe,CAAC;AAExD;;;;;GAKG;AACH,2BAAqC,KAA8B;IAChE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,KAAoC,CAAC;IACvD,OAAO,OAAO,IAAI,SAAS,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU,CAAC;AAC3E,CAAC;AAED,IAAiB,eAAe,CAoB/B;AApBD,WAAiB,eAAe;IAC7B;;;;;OAKG;IACH,SAAgB,EAAE,CAAI,KAAQ;QAC3B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAuB,EAAE,CAAC;IACvD,CAAC;IAFe,gBAAA,EAAE,KAEjB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,IAAI,CAAI,KAA8B;QACnD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAFe,gBAAA,IAAI,OAEnB,CAAA;AACJ,CAAC,EApBgB,eAAe,aAAf,eAAe,GAAf,eAAe,QAoB/B"}

package/lib/patch-merge.d.ts

@@ -8,58 +8,60 @@
  ********************************************************************************/
 import { type Operation as JsonPatchOperation } 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 declare function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[];
+export declare function augmentWithTestOps(base: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[];
 /**
- * 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`,
+ * catches up with the server on `no-op`, and decides its own fallback (e.g.
+ * force-retry) on `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
-     * 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';
 } | {
-    /** 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;
 } | {
     /**
      * The refetch produced nothing, so reconciliation could not be
@@ -70,22 +72,23 @@ 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
- *   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`.
+ * - `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 declare function reconcileByPatchReplay<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+export declare function reconcileByPatchReplay<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
 /**
  * Strategy for resolving a write that raced a foreign edit. One declarative
  * choice covers every conflict site — `execute` forward-write `(before,
@@ -95,12 +98,12 @@ export declare function reconcileByPatchReplay<T extends object>(baseline: T, at
  */
 export interface ConflictResolver {
     /**
-     * Reconcile the user's `baseline → attempted` intent against the current
-     * server state (`refetch`), returning a {@link ReconcileOutcome} the caller
-     * acts on (persist `merged`, drop on `conflict`, fall back on `no-op` /
-     * `unavailable`).
+     * 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`, catch up on `no-op`, fall
+     * back on `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>>;
 }
 /**
  * Default {@link ConflictResolver}: field-level three-way merge via
@@ -109,15 +112,15 @@ export interface ConflictResolver {
  * clobbered.
  */
 export declare class ReconcilingConflictResolver implements ConflictResolver {
-    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>>;
 }
 /**
- * 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 declare class ForceConflictResolver implements ConflictResolver {
-    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>>;
 }
 //# sourceMappingURL=patch-merge.d.ts.map

package/lib/patch-merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch-merge.d.ts","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqD,KAAK,SAAS,IAAI,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1H;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,EAAE,CASvH;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IACzB;IACG,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,CAAC;IACjB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC;CACZ,GACD;IACG;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;CAClB,GACD;IACG,6EAA6E;IAC7E,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC;CACX,GACD;IACG;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;CACxB,CAAC;AAEP;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EAC1D,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACrC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAe9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5H;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IACjE,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAG3H;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IACrD,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAGnI"}
+{"version":3,"file":"patch-merge.d.ts","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAMJ,KAAK,SAAS,IAAI,kBAAkB,EAEtC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,EAAE,CASnH;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IACzB;IACG,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACZ,GACD;IACG;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;CAClB,GACD;IACG,uFAAuF;IACvF,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACZ,GACD;IACG;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;CACxB,CAAC;AAEP;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EAC1D,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACrC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAkB9B;AA2CD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;CACnH;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IACjE,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAE/G;CACH;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IACrD,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAEvH;CACH"}