@hydranium/protocol 1.0.0-next.22 → 1.0.0-next.220

package/src/node/process-memory.ts

@@ -0,0 +1,299 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * 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`.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as v8 from 'node:v8';
+import { Format } from '../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`.
+ */
+export function formatProcessMemory(label: string): string {
+   const mem = process.memoryUsage();
+   const heap = v8.getHeapStatistics();
+   const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+   return [
+      `${label}:`,
+      `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+         `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
+      `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${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.
+ */
+export function snapshotFilePath(directory: string | undefined, label: string, prefix: string, ext: string): string {
+   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.
+ */
+export function writeHeapSnapshotToDir(directory: string | undefined, label: string, prefix = 'server-heap'): string {
+   const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
+   v8.writeHeapSnapshot(filePath);
+   return filePath;
+}
+
+const CGROUP_ROOT = '/sys/fs/cgroup';
+
+function readNumber(file: string): number | undefined {
+   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: string): Record<string, number> {
+   const out: Record<string, number> = {};
+   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;
+}
+
+interface ProcInfo {
+   pid: number;
+   rssBytes: number;
+   label: string;
+}
+
+interface RawProc extends ProcInfo {
+   ppid: number;
+}
+
+/** A readable role for a process, whether it belongs to the app, and whether exactly one is expected. */
+export interface ProcessRole {
+   /** Human-readable role shown in the snapshot. */
+   role: string;
+   /** Whether this process is part of the application (vs. tooling/debugger), counted in the app total. */
+   isApp: boolean;
+   /**
+    * Set when at most one instance of this role should exist; `formatPodMemory` warns when more than
+    * one is found (e.g. a duplicated/ghost language server).
+    */
+   singletonExpected?: boolean;
+}
+
+/** Map a raw command line to a {@link ProcessRole}. A head supplies this to label its own processes. */
+export type ProcessClassifier = (cmdline: string) => ProcessRole;
+
+/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
+const defaultProcessClassifier: ProcessClassifier = 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(): RawProc[] {
+   const procs: RawProc[] = [];
+   let entries: string[] = [];
+   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?: number): { total: number; processes: ProcInfo[]; scoped: boolean } {
+   const all = readAllProcs();
+   let selected: RawProc[] = all;
+   let scoped = false;
+   if (rootPid !== undefined) {
+      const childrenByPpid = new Map<number, RawProc[]>();
+      for (const proc of all) {
+         (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)!).push(proc);
+      }
+      const tree: RawProc[] = [];
+      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 };
+}
+
+/** Options for {@link formatPodMemory}. */
+export interface PodMemoryOptions {
+   /** Map a process command line to a readable role; lets a head label its own processes. */
+   classify?: ProcessClassifier;
+   /** Heading for the in-app process group (default `Application`). */
+   appLabel?: string;
+}
+
+/**
+ * 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).
+ */
+export function formatPodMemory(options: PodMemoryOptions = {}): string {
+   const classify = options.classify ?? defaultProcessClassifier;
+   const appLabel = options.appLabel ?? 'Application';
+   const lines: string[] = ['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 ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
+      lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? Format.bytes(max) : 'n/a'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown anon ${Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${Format.bytes(stat.file ?? 0)} (page cache), ` +
+               `kernel ${Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${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 ? Format.bytes(current) : 'n/a'}`);
+      lines.push(`  peak      ${peak !== undefined ? 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 ? Format.bytes(limit) : 'unlimited'}`);
+      if (Object.keys(stat).length > 0) {
+         lines.push(
+            `  breakdown rss ${Format.bytes(stat.rss ?? 0)}, cache ${Format.bytes(stat.cache ?? 0)} (page cache), ` +
+               `kernel ${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}: ${Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
+      for (const proc of appProcs) {
+         lines.push(`    ${Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
+      }
+      const singletonCounts = new Map<string, number>();
+      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): ${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');
+}

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,40 @@ 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`,
+ * 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;
      }
    | {
         /**
@@ -87,39 +97,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
- *   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 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 +187,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
-    * 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>>;
 }
 
 /**
@@ -147,19 +202,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/profile-session.ts

@@ -62,7 +62,12 @@ export interface ProfileSession {
    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;
@@ -78,7 +83,7 @@ interface ScopeFrame {
 export class DefaultProfileSession implements ProfileSession {
    /** 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 = new Map<string, number[]>();
 
    constructor(
@@ -92,7 +97,7 @@ export class DefaultProfileSession implements ProfileSession {
    scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
    scope<T>(id: string, fn: () => T): T;
    scope<T>(id: string, fn: () => T | Promise<T>): T | Promise<T> {
-      const frame: ScopeFrame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
+      const frame: ProfileScopeFrame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
       this.stack.push(frame);
       let result: T | Promise<T>;
       try {
@@ -118,7 +123,7 @@ export class DefaultProfileSession implements ProfileSession {
    }
 
    /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
-   protected closeFrame(frame: ScopeFrame): void {
+   protected closeFrame(frame: ProfileScopeFrame): void {
       this.stack.pop();
       const duration = this.sessionStopwatch.elapsedMs - frame.start;
       const parent = this.stack[this.stack.length - 1];

package/src/random-uuid.ts

@@ -0,0 +1,21 @@
+/********************************************************************************
+ * 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 function randomUuid(): string {
+   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)}`;
+}