@hydranium/protocol 1.0.0-next.36 → 1.0.0-next.361

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,60 @@ 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, takes `theirs` as the new base on
+ * `already-applied`, 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. */
+        /**
+         * The replay succeeded: the foreign writer touched no path the user
+         * did, or wrote the user's value at one that runs through no array.
+         */
         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. */
+        /** The refetch already holds every path the user changed at the user's value: nothing is left to write. */
+        status: 'already-applied';
+        /**
+         * The server's current root, refetched and unmodified. Take it as the
+         * new base, not `ours`: it can also hold another writer's edit to a
+         * path the user did not change.
+         */
+        theirs: T;
+     }
+   | {
+        /**
+         * User and foreign writer changed one path to different values, or
+         * both changed one inside an array the refetch holds otherwise than
+         * the user, even to the same value; both inserted the same array
+         * element; or the foreign writer removed or replaced what the user
+         * edited inside.
+         */
         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 +117,194 @@ 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`.
+ * - `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.
  */
 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' };
    }
+   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 = applyPatch(deepClone(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+      const merged = applyPatch(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: object, ours: object, theirs: object, userPatch: readonly JsonPatchOperation[]): JsonPatchOperation[] {
+   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<string, boolean>();
+   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) && _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 = 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) || !_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: object, pointer: string): string | undefined {
+   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<T>(value: T): T {
+   return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/**
+ * 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: object, theirs: object, userPatch: readonly JsonPatchOperation[]): boolean {
+   // Each array's elements are counted once, however many ops insert into it, so a bulk insert stays linear.
+   const tallies = new Map<string, { readonly before: ReadonlyMap<string, number>; readonly now: ReadonlyMap<string, number> }>();
+   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, unescapePathComponent(op.path.slice(cut + 1)));
+   });
+}
+
+/** How many elements of `array` there are of each value, keyed by {@link canonicalJson}. */
+function tallyElements(array: readonly unknown[]): ReadonlyMap<string, number> {
+   const tally = new Map<string, number>();
+   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: unknown): string {
+   return JSON.stringify(value, (_key, nested: unknown) =>
+      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: object, pointer: string): unknown {
+   try {
+      return getValueByPointer(document, pointer);
+   } catch {
+      return undefined;
    }
 }
 
@@ -132,12 +317,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`, write nothing on `already-applied`, 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 +332,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/pending-work-tracker.ts

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * Watches work started elsewhere until it settles, so a caller can ask whether
+ * any is still pending and wait for what is pending now. It starts, orders and
+ * limits nothing, and keeps no clock: a caller that must not wait for good
+ * races {@link whenSettled} against its own bound.
+ */
+export class PendingWorkTracker {
+   /** The tracked work. {@link track} removes each entry once it settles. */
+   protected readonly pending = new Set<Promise<unknown>>();
+
+   /** Watch `work` until it settles, and hand it back. */
+   track<T>(work: Promise<T>): Promise<T> {
+      this.pending.add(work);
+      const done = (): void => {
+         this.pending.delete(work);
+      };
+      work.then(done, done);
+      return work;
+   }
+
+   /** How much of the tracked work has not settled yet. */
+   get size(): number {
+      return this.pending.size;
+   }
+
+   /** Whether all tracked work has settled. Synchronous, for a check that must decide within the tick. */
+   get isIdle(): boolean {
+      return this.pending.size === 0;
+   }
+
+   /**
+    * Resolves once the work pending now has settled; work tracked later is not
+    * waited for. Never rejects, since failed work has settled too.
+    */
+   async whenSettled(): Promise<void> {
+      await Promise.allSettled([...this.pending]);
+   }
+}

package/src/profile-session.ts

@@ -18,7 +18,11 @@ export interface ProfileRecord {
    count: number;
    /** Summed self-time across those runs (wall-clock minus nested scopes). */
    selfMs: number;
-   /** Self-time as a percentage of the session's total wall-clock. */
+   /**
+    * Self-time as a percentage of the session's total wall-clock. Overlapping
+    * scopes each count their own wall time, so the percentages can add up to
+    * more than 100.
+    */
    selfPct: number;
 }
 
@@ -53,8 +57,9 @@ export interface ProfileSession {
    /**
     * Emit the aggregate through the bound {@link Logger}: one line per id,
     * sorted by self-time descending, plus an "unaccounted" remainder (the
-    * session wall-clock not attributed to any top-level scope). No-op when
-    * `logLevel` is suppressed by the global threshold (incl. `'off'`).
+    * session wall-clock not attributed to any top-level scope). The remainder
+    * is left out when overlapping scopes account for more than the wall-clock.
+    * No-op when `logLevel` is suppressed by the global threshold (incl. `'off'`).
     */
    report(logLevel?: LogThreshold): void;
 
@@ -62,7 +67,13 @@ 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 {
+   /** The {@link ProfileSession.scope} id, under which frames sharing it aggregate into one record. */
    readonly id: string;
    /** Session-stopwatch reading when this scope began. */
    readonly start: number;
@@ -78,7 +89,9 @@ 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[] = [];
+   /** The scopes in flight, in the order they started. */
+   protected readonly stack: ProfileScopeFrame[] = [];
+   /** Self-time in milliseconds per id, one sample per closed scope, which {@link records} sums. */
    protected readonly entries = new Map<string, number[]>();
 
    constructor(
@@ -92,7 +105,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 {
@@ -117,15 +130,22 @@ export class DefaultProfileSession implements ProfileSession {
       return result;
    }
 
-   /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
-   protected closeFrame(frame: ScopeFrame): void {
-      this.stack.pop();
+   /**
+    * Remove `frame`, charge its full duration to the frame below it, and record
+    * its self-time. Overlapping scopes can together outlast the one below
+    * them, whose self-time is then zero rather than negative.
+    */
+   protected closeFrame(frame: ProfileScopeFrame): void {
+      const index = this.stack.lastIndexOf(frame);
+      if (index >= 0) {
+         this.stack.splice(index, 1);
+      }
       const duration = this.sessionStopwatch.elapsedMs - frame.start;
-      const parent = this.stack[this.stack.length - 1];
+      const parent = index > 0 ? this.stack[index - 1] : undefined;
       if (parent) {
          parent.childMs += duration;
       }
-      const selfMs = duration - frame.childMs;
+      const selfMs = Math.max(0, duration - frame.childMs);
       const samples = this.entries.get(frame.id);
       if (samples) {
          samples.push(selfMs);

package/src/profiling.ts

@@ -17,15 +17,23 @@
 
 /** Which dimensions to capture, and the two sampling knobs. All off by default. */
 export interface ProfileCaptureOptions {
+   /** Sample the CPU at {@link cpuIntervalMicros} into a `server-cpu` artefact. */
    cpu?: boolean;
+   /** Sample allocations at {@link allocationIntervalBytes} into a `server-alloc` artefact. */
    allocation?: boolean;
+   /** Record every GC pause, summed by kind in `server-summary` rather than as its own artefact. */
    gc?: boolean;
+   /**
+    * Sample event-loop delay, summarised as mean, p50, p99 and max in
+    * `server-summary` rather than as its own artefact. Absent there when the
+    * sampler recorded nothing.
+    */
    eventLoopDelay?: boolean;
    /** Also drop a retained `.heapsnapshot` at stop (for the memory analyzer). */
    heapSnapshot?: boolean;
-   /** CPU sampling interval in µs (implementation default 1000). */
+   /** CPU sampling interval in µs (implementation default `DEFAULT_CPU_INTERVAL_MICROS`). */
    cpuIntervalMicros?: number;
-   /** Allocation sampling interval in bytes (implementation default 32768). */
+   /** Allocation sampling interval in bytes (implementation default `DEFAULT_ALLOCATION_INTERVAL_BYTES`). */
    allocationIntervalBytes?: number;
 }
 
@@ -72,12 +80,17 @@ export interface ProfilingArtifact {
 
 /** What a skill reads to know what to expect from a run (browser entries only in `app` mode, etc.). */
 export interface ProfilingEnvironment {
+   /** `harness` for a headless run, `app` for one that drove the real app. */
    mode: 'harness' | 'app';
    /** Whether a cgroup memory controller is present (running in a pod) vs local. */
    container: boolean;
+   /** The commit the run reflects, which a finding's `file:line` is read against. Absent when the caller named none. */
    commit?: string;
+   /** The workspace under test as the caller named it. Absent when it named none. */
    workspace?: string;
+   /** The `process.version` of the process that wrote the manifest, which for an e2e run is the test runner, not the server. */
    node: string;
+   /** Captured windows in capture order, each with its duration in milliseconds. */
    windows: { label: string; ms: number }[];
 }
 

package/src/project.ts

@@ -40,7 +40,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/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)}`;
+}