mandrel 2.47.0 → 2.48.0

package/.agents/docs/configuration.md

@@ -690,6 +690,7 @@ Claude Code web environment-variables UI for web sessions.
 | `WEBHOOK_SECRET`           | No        | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads.                                 |
 | `MANDREL_ALLOW_TEST_WEBHOOKS` | No     | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
 | `MANDREL_POOL_CONCURRENCY` | No | Upper bound on the width of every `runOnPool` worker pool in the process (the MI and CRAP scan pools). Precedence is: a caller's explicit `concurrency` → this variable → a clamp of 4 under `node:test` → `os.availableParallelism()`. Set it on a constrained or shared runner where one pool per core oversubscribes the host; a non-numeric value is ignored rather than collapsing the pool. |
+| `MANDREL_BASELINE_GENERATED_AT` | No | Pins the `generatedAt` stamp every baseline envelope carries, instead of reading the clock. Set it for a reproducible build, or to make a hand-run refresh diff against a known stamp. It changes only the stamp — rows and rollup are unaffected, and a refresh that moves no row still rewrites nothing. Concurrent refreshes no longer need it to avoid conflicting: `baselines/*.json` merges by row identity (see the baseline merge driver in [quality-gates.md](quality-gates.md)). |
 | `MANDREL_AGENTRC_VALIDATOR` | No | Set to `dynamic` to compile the `.agentrc.json` AJV validator at runtime instead of loading the committed precompiled one (see below). Costs ~35 ms per process; the escape hatch exists for a hand-edited schema or a host where the generated module will not load. |
 
 ### The `.agentrc` validator is precompiled

package/.agents/docs/quality-gates.md

@@ -889,6 +889,54 @@ The schemas live under [`.agents/schemas/baselines/`](../schemas/baselines/).
 The shared AJV instance is built by `buildBaselineSchemaAjv()` in
 [`.agents/scripts/lib/baseline-schema-registry.js`](../scripts/lib/baseline-schema-registry.js).
 
+### Concurrent refreshes — the baseline merge driver
+
+`generatedAt` sits on line 4 of every envelope, so two branches that each
+refresh a baseline **always** differ there, even when they moved completely
+disjoint rows. Git merges JSON as text, and whether it can separate that hunk
+from the moved rows is an accident of proximity. Both outcomes are wrong:
+
+- it cannot → a conflict on work that never overlapped (the `coverage.json` /
+  `maintainability.json` "always conflicts" pattern);
+- it can → it splices both sides' row lines into a row set **neither side
+  scored** (the `crap.json` "silently auto-merges" pattern). The ratchet then
+  guards a number no scorer ever produced.
+
+A baseline is a set of rows keyed by identity plus a rollup derived from them,
+so [`merge-baseline.js`](../scripts/merge-baseline.js) merges it as that. Per
+row identity the standard 3-way rule applies; only a genuine double move
+conflicts, and then markers wrap that row alone. The rollup is always
+**recomputed** from the merged rows — merging two rollups is the same splice
+hazard compressed into one number — and `generatedAt` resolves to the later of
+the two stamps rather than conflicting.
+
+Row identity comes from the kind module's `rowIdentity(row)`, which is
+deliberately not `keyField`: CRAP groups by file (`keyField: 'path'`) but
+ships one row per method, so keying on `keyField` would drop every method in a
+file but one. Any `baselines/*.json` whose `$schema` is not a known per-kind
+envelope — `arch-cycles`, `cyclomatic`, `dead-exports`, `audit-ledger`,
+`context-budget`, `workflow-citations` — is handed straight back to
+`git merge-file`, so registering the driver cannot change their behaviour.
+
+Registration has two halves:
+
+```bash
+# 1. tracked, installed by `node .agents/scripts/apply-quality-bootstrap.js`
+#    → .gitattributes:  baselines/*.json merge=mandrel-baseline
+# 2. per clone — git will not run a command chosen by whoever wrote the repo
+git config merge.mandrel-baseline.driver "node .agents/scripts/merge-baseline.js %O %A %B %P"
+```
+
+Only the first ships with the repository, and a clone missing the second
+degrades **silently** back to the text merge. `mandrel doctor`'s
+`merge-driver` check is the guard: it prints the exact `git config` line
+above, and passes as skipped when `.gitattributes` does not declare the
+driver at all.
+
+`MANDREL_BASELINE_GENERATED_AT` pins the stamp for a reproducible build (see
+the environment table in [configuration.md](configuration.md)). It is no
+longer needed to dodge merge conflicts.
+
 ### Per-kind shapes
 
 Each kind contributes a `rows[]` schema and a `rollup` axis set. The

package/.agents/scripts/lib/baselines/kernel.js

@@ -35,6 +35,7 @@ import {
   name as bundleSizeName,
   projectRow as bundleSizeProjectRow,
   rollup as bundleSizeRollup,
+  rowIdentity as bundleSizeRowIdentity,
   sortRows as bundleSizeSortRows,
 } from './kinds/bundle-size.js';
 import {
@@ -46,6 +47,7 @@ import {
   name as coverageName,
   projectRow as coverageProjectRow,
   rollup as coverageRollup,
+  rowIdentity as coverageRowIdentity,
   sortRows as coverageSortRows,
 } from './kinds/coverage.js';
 import {
@@ -59,6 +61,7 @@ import {
   name as crapName,
   projectRow as crapProjectRow,
   rollup as crapRollup,
+  rowIdentity as crapRowIdentity,
   sortRows as crapSortRows,
 } from './kinds/crap.js';
 import {
@@ -70,6 +73,7 @@ import {
   name as duplicationName,
   projectRow as duplicationProjectRow,
   rollup as duplicationRollup,
+  rowIdentity as duplicationRowIdentity,
   sortRows as duplicationSortRows,
 } from './kinds/duplication.js';
 import {
@@ -81,6 +85,7 @@ import {
   name as lighthouseName,
   projectRow as lighthouseProjectRow,
   rollup as lighthouseRollup,
+  rowIdentity as lighthouseRowIdentity,
   sortRows as lighthouseSortRows,
 } from './kinds/lighthouse.js';
 import {
@@ -92,6 +97,7 @@ import {
   name as lintName,
   projectRow as lintProjectRow,
   rollup as lintRollup,
+  rowIdentity as lintRowIdentity,
   sortRows as lintSortRows,
 } from './kinds/lint.js';
 import {
@@ -103,6 +109,7 @@ import {
   name as maintainabilityName,
   projectRow as maintainabilityProjectRow,
   rollup as maintainabilityRollup,
+  rowIdentity as maintainabilityRowIdentity,
   sortRows as maintainabilitySortRows,
 } from './kinds/maintainability.js';
 import {
@@ -115,6 +122,7 @@ import {
   name as mutationName,
   projectRow as mutationProjectRow,
   rollup as mutationRollup,
+  rowIdentity as mutationRowIdentity,
   sortRows as mutationSortRows,
 } from './kinds/mutation.js';
 
@@ -135,6 +143,9 @@ function bindKindModule(members) {
   return Object.freeze({
     name: members.name,
     keyField: members.keyField,
+    // Story #5215: the merge identity, distinct from the `keyField`
+    // grouping key above — CRAP groups by file and identifies by method.
+    rowIdentity: members.rowIdentity,
     kernelVersion: members.kernelVersion,
     projectRow: members.projectRow,
     sortRows: members.sortRows,
@@ -159,6 +170,7 @@ const KIND_MODULES = Object.freeze({
   lint: bindKindModule({
     name: lintName,
     keyField: lintKeyField,
+    rowIdentity: lintRowIdentity,
     kernelVersion: lintKernelVersion,
     projectRow: lintProjectRow,
     sortRows: lintSortRows,
@@ -170,6 +182,7 @@ const KIND_MODULES = Object.freeze({
   coverage: bindKindModule({
     name: coverageName,
     keyField: coverageKeyField,
+    rowIdentity: coverageRowIdentity,
     kernelVersion: coverageKernelVersion,
     projectRow: coverageProjectRow,
     sortRows: coverageSortRows,
@@ -181,6 +194,7 @@ const KIND_MODULES = Object.freeze({
   crap: bindKindModule({
     name: crapName,
     keyField: crapKeyField,
+    rowIdentity: crapRowIdentity,
     kernelVersion: crapKernelVersion,
     projectRow: crapProjectRow,
     sortRows: crapSortRows,
@@ -194,6 +208,7 @@ const KIND_MODULES = Object.freeze({
   maintainability: bindKindModule({
     name: maintainabilityName,
     keyField: maintainabilityKeyField,
+    rowIdentity: maintainabilityRowIdentity,
     kernelVersion: maintainabilityKernelVersion,
     projectRow: maintainabilityProjectRow,
     sortRows: maintainabilitySortRows,
@@ -205,6 +220,7 @@ const KIND_MODULES = Object.freeze({
   mutation: bindKindModule({
     name: mutationName,
     keyField: mutationKeyField,
+    rowIdentity: mutationRowIdentity,
     kernelVersion: mutationKernelVersion,
     projectRow: mutationProjectRow,
     sortRows: mutationSortRows,
@@ -217,6 +233,7 @@ const KIND_MODULES = Object.freeze({
   lighthouse: bindKindModule({
     name: lighthouseName,
     keyField: lighthouseKeyField,
+    rowIdentity: lighthouseRowIdentity,
     kernelVersion: lighthouseKernelVersion,
     projectRow: lighthouseProjectRow,
     sortRows: lighthouseSortRows,
@@ -228,6 +245,7 @@ const KIND_MODULES = Object.freeze({
   'bundle-size': bindKindModule({
     name: bundleSizeName,
     keyField: bundleSizeKeyField,
+    rowIdentity: bundleSizeRowIdentity,
     kernelVersion: bundleSizeKernelVersion,
     projectRow: bundleSizeProjectRow,
     sortRows: bundleSizeSortRows,
@@ -239,6 +257,7 @@ const KIND_MODULES = Object.freeze({
   duplication: bindKindModule({
     name: duplicationName,
     keyField: duplicationKeyField,
+    rowIdentity: duplicationRowIdentity,
     kernelVersion: duplicationKernelVersion,
     projectRow: duplicationProjectRow,
     sortRows: duplicationSortRows,

package/.agents/scripts/lib/baselines/kinds/bundle-size.js

@@ -28,6 +28,18 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Canonical row identity (Story #5215). This kind does not use the shared
+ * factory scaffold, so it declares the protocol member itself; `bundle` is
+ * unique per row here, which a shipped-baseline injectivity test pins.
+ *
+ * @param {{bundle: string, rawKb: number, gzippedKb: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
+  return row.bundle;
+}
+
 export function sortRows(rows) {
   return [...rows].sort((a, b) => a.bundle.localeCompare(b.bundle));
 }

package/.agents/scripts/lib/baselines/kinds/coverage.js

@@ -61,6 +61,7 @@ function perfectCoverageRow(path) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -242,14 +242,30 @@ export const rollup = makeRollup({ aggregate });
  * No I/O. No process exit. No friction emission.
  */
 export const compare = makeCompare({
-  identity: crapRowKey,
+  identity: rowIdentity,
   betterIsHigher: false,
   metricField: 'crap',
   // Removed methods whose crap > 0 are improvements (the debt is gone).
   removedIsImprovement: (b) => (b.crap ?? 0) > 0,
 });
 
-function crapRowKey(row) {
+/**
+ * Canonical CRAP row identity (Story #5215) — the composite
+ * `path::method@startLine`, exported under the protocol name every kind
+ * module answers to.
+ *
+ * This kind is the reason identity is a separate concept from `keyField`.
+ * `keyField` is `'path'` because the rollup groups by file, but a file
+ * ships one row per method, so a merge keyed on `keyField` would collapse
+ * every method in a file to one row and drop the rest. `compare`,
+ * `applyEpsilon` and `mergeRows` have always keyed on this composite;
+ * exporting it makes the same identity available to callers that used to
+ * have no choice but to guess from `keyField`.
+ *
+ * @param {{path: string, method: string, startLine: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
   return `${row.path}::${row.method}@${row.startLine}`;
 }
 
@@ -258,7 +274,7 @@ function crapRowKey(row) {
 // absorbed the per-file queue wiring, both callers are inside it, so the
 // exports — and the re-export that used to live here — were reachable from
 // tests alone. `resolveIncrementalContext` is the production door to the
-// index; `crapRowKey` above is the composite key it halves.
+// index; `rowIdentity` above is the composite key it halves.
 
 /**
  * Pure stabilizer for s-stability-epsilon (Story #1964). CRAP rows match
@@ -271,7 +287,7 @@ function crapRowKey(row) {
  * @returns {Array<object>}
  */
 export const applyEpsilon = makeEpsilon({
-  identity: crapRowKey,
+  identity: rowIdentity,
   metricField: 'crap',
 });
 
@@ -294,7 +310,7 @@ export function mergeRows(prior, regenerated, scope) {
     regenerated,
     scope,
     scopeKey: (row) => row.path,
-    identity: (row) => crapRowKey(row),
+    identity: (row) => rowIdentity(row),
   });
 }
 

package/.agents/scripts/lib/baselines/kinds/duplication.js

@@ -89,6 +89,7 @@ function roundTo2(value) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/kinds/kind-factory.js

@@ -38,7 +38,10 @@ import { mergeRowsByScope } from '../scope.js';
  *     | { kind: 'improvement-when', when: (row: object) => boolean },
  *   perfectRow?: (key: string) => object,
  * }} opts
- *   - `keyField`          — row identity property (`'path'` or `'route'`)
+ *   - `keyField`          — row grouping property (`'path'` or `'route'`):
+ *                           the rollup/scope key. The generated
+ *                           `rowIdentity` derives from it, but the two are
+ *                           distinct concepts — see `rowIdentity` below.
  *   - `kernelVersion`     — static semver, or a thunk for kinds that pin
  *                           to another kind's kernel (MI → CRAP)
  *   - `axes`              — metric property names compared per row
@@ -57,6 +60,7 @@ import { mergeRowsByScope } from '../scope.js';
  *   - `perfectRow`        — builds the perfect row for the policies above
  * @returns {{
  *   kernelVersion: () => string,
+ *   rowIdentity: (row: object) => string,
  *   sortRows: (rows: object[]) => object[],
  *   rollup: (rows: object[], components?: object[]) => Record<string, object>,
  *   compare: (head: object, base: object) => object,
@@ -78,6 +82,26 @@ export function makeBaselineKind({
   const kernelVersionFn =
     typeof kernelVersion === 'function' ? kernelVersion : () => kernelVersion;
 
+  /**
+   * Canonical row identity (Story #5215) — the string a 3-way merge keys a
+   * row on, and the contract every kind module must satisfy.
+   *
+   * Deliberately a separate concept from `keyField`, even though the five
+   * scaffold kinds derive one from the other. `keyField` answers "which
+   * component does this row roll up into", so a kind is free to declare a
+   * grouping key coarser than a row (CRAP declares `'path'` while shipping
+   * one row per method). Identity answers "is this the same row", and a
+   * merge that confuses the two silently drops every sibling sharing a key.
+   * Callers therefore read `rowIdentity` off the kind module and never
+   * rebuild a key from `keyField` themselves.
+   *
+   * @param {object} row
+   * @returns {string}
+   */
+  function rowIdentity(row) {
+    return String(keyOf(row));
+  }
+
   function sortRows(rows) {
     return [...rows].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
   }
@@ -183,6 +207,7 @@ export function makeBaselineKind({
 
   return {
     kernelVersion: kernelVersionFn,
+    rowIdentity,
     sortRows,
     rollup,
     compare,

package/.agents/scripts/lib/baselines/kinds/lighthouse.js

@@ -69,6 +69,7 @@ function perfectLighthouseRow(route) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/kinds/lint.js

@@ -67,6 +67,18 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Canonical row identity (Story #5215). This kind does not use the shared
+ * factory scaffold, so it declares the protocol member itself; `path` is
+ * unique per row here, which a shipped-baseline injectivity test pins.
+ *
+ * @param {{path: string, errorCount: number, warningCount: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
+  return row.path;
+}
+
 export function sortRows(rows) {
   return [...rows].sort((a, b) => a.path.localeCompare(b.path));
 }

package/.agents/scripts/lib/baselines/kinds/maintainability.js

@@ -109,6 +109,7 @@ function aggregate(rows) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/kinds/mutation.js

@@ -178,6 +178,7 @@ function aggregate(rows) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/merge-envelopes.js

@@ -0,0 +1,272 @@
+/**
+ * merge-envelopes.js — pure 3-way merge of baseline envelopes by row
+ * identity (Story #5215).
+ *
+ * ## Why this exists
+ *
+ * Every baseline write stamps `generatedAt`, and the stamp sits on line 4 of
+ * every envelope. Two branches that each refresh a baseline therefore always
+ * differ on that line, even when they moved completely disjoint rows — so
+ * git's LINE-based merge has to reconcile it. Whether it can separate that
+ * hunk from the moved rows is an accident of proximity, and both outcomes
+ * are bad:
+ *
+ *   - it cannot → a conflict on work that never actually overlapped;
+ *   - it can → it splices both sides' row lines together into a row set
+ *     NEITHER side ever scored. That silent one is the worse failure: the
+ *     ratchet then guards a number no scorer produced.
+ *
+ * A baseline is not a text file. It is a set of rows keyed by identity plus
+ * a rollup DERIVED from those rows, so merging it as text is a category
+ * error. This module merges it as what it is.
+ *
+ * ## Contract
+ *
+ * Pure: no filesystem, no process, no clock. `assertEnvelope` is deliberately
+ * NOT called here (it compiles schemas off disk on first use) — the driver
+ * validates what this returns.
+ *
+ * Per row identity, the standard 3-way rule: the side that differs from base
+ * wins; when both sides differ from base AND from each other, that identity
+ * is a conflict. Absence is a value, so a row deleted on one side and
+ * untouched on the other merges to deleted.
+ *
+ * Two invariants are load-bearing:
+ *
+ *   1. **The rollup is recomputed, never merged.** Merging two rollups is
+ *      the same splice hazard compressed into a single number, and unlike a
+ *      spliced row set it leaves no evidence. It is always derived from the
+ *      merged rows via the kind's own `rollup()`.
+ *   2. **Identity comes from the kind module** (`rowIdentity`), never from
+ *      `keyField`. CRAP groups by file and identifies by method; keying on
+ *      `keyField` would drop every method in a file but one.
+ *
+ * @module lib/baselines/merge-envelopes
+ */
+
+import { deepEqual } from '../json-utils.js';
+import { KNOWN_KINDS } from './envelope.js';
+import { getKindModule } from './kernel.js';
+
+/**
+ * Envelope keys that are NOT merged side-by-side: `rows` merge by identity,
+ * `rollup` is recomputed from them, and `generatedAt` resolves to the later
+ * of the two stamps rather than conflicting (it is metadata about when a
+ * scorer ran, not a scored value — treating it as content is the whole bug).
+ */
+const DERIVED_KEYS = Object.freeze(['rows', 'rollup', 'generatedAt']);
+
+/**
+ * Identify an envelope's kind from its `$schema` reference.
+ *
+ * Derived from `KNOWN_KINDS` rather than pattern-matched, so a file that is
+ * not a known per-kind envelope answers `null` — which is how the driver
+ * knows to hand it back to git's text merge instead of guessing at a shape
+ * it does not understand. `baselines/*.json` also matches several
+ * non-envelope baselines (arch-cycles, cyclomatic, dead-exports, …).
+ *
+ * @param {unknown} envelope
+ * @returns {string|null}
+ */
+export function kindFromEnvelope(envelope) {
+  const ref = envelope?.$schema;
+  if (typeof ref !== 'string') return null;
+  const base = ref.split('/').pop();
+  for (const kind of KNOWN_KINDS) {
+    if (base === `${kind}.schema.json`) return kind;
+  }
+  return null;
+}
+
+/**
+ * The 3-way choice for one value. `undefined` means "absent on this side",
+ * which makes deletion just another value rather than a special case.
+ *
+ * @param {unknown} base
+ * @param {unknown} ours
+ * @param {unknown} theirs
+ * @returns {{ conflict: boolean, value?: unknown }}
+ */
+function choose(base, ours, theirs) {
+  if (deepEqual(ours, theirs)) return { conflict: false, value: ours };
+  if (deepEqual(ours, base)) return { conflict: false, value: theirs };
+  if (deepEqual(theirs, base)) return { conflict: false, value: ours };
+  return { conflict: true };
+}
+
+/**
+ * Index rows by the kind's `rowIdentity`. A duplicate identity within one
+ * side is fatal rather than last-write-wins: it means the incoming file
+ * already violates the identity contract, and merging it would silently
+ * drop a row.
+ *
+ * @param {Array<object>} rows
+ * @param {(row: object) => string} rowIdentity
+ * @param {string} side
+ * @returns {Map<string, object>}
+ */
+function indexRows(rows, rowIdentity, side) {
+  const out = new Map();
+  for (const [idx, row] of (rows ?? []).entries()) {
+    if (!row || typeof row !== 'object') {
+      throw new TypeError(
+        `mergeEnvelopes: ${side} row at index ${idx} is not an object`,
+      );
+    }
+    const id = rowIdentity(row);
+    if (out.has(id)) {
+      throw new Error(
+        `mergeEnvelopes: ${side} carries two rows with identity "${id}" — the baseline violates the identity contract and cannot be merged safely`,
+      );
+    }
+    out.set(id, row);
+  }
+  return out;
+}
+
+/**
+ * Resolve `generatedAt` to the later of the two sides. A stamp is metadata,
+ * so it never conflicts: the merged file describes a tree scored as recently
+ * as the newer of its inputs.
+ *
+ * @param {string|undefined} ours
+ * @param {string|undefined} theirs
+ * @returns {string|undefined}
+ */
+function laterStamp(ours, theirs) {
+  if (typeof ours !== 'string') return theirs;
+  if (typeof theirs !== 'string') return ours;
+  const a = Date.parse(ours);
+  const b = Date.parse(theirs);
+  if (Number.isNaN(a) || Number.isNaN(b)) return ours > theirs ? ours : theirs;
+  return a >= b ? ours : theirs;
+}
+
+/**
+ * Merge the envelope-level stamps (`$schema`, `kernelVersion`, and per-kind
+ * extras like `scoringSemantics`) by the same 3-way rule as rows. A double
+ * bump to different values is a genuine conflict — two branches disagreeing
+ * about which scorer produced the file.
+ *
+ * @param {object} base
+ * @param {object} ours
+ * @param {object} theirs
+ * @returns {{ merged: object, conflicts: Array<object> }}
+ */
+function mergeStamps(base, ours, theirs) {
+  const keys = new Set(
+    [...Object.keys(ours), ...Object.keys(theirs), ...Object.keys(base)].filter(
+      (k) => !DERIVED_KEYS.includes(k),
+    ),
+  );
+  const merged = {};
+  const conflicts = [];
+  for (const key of keys) {
+    const pick = choose(base[key], ours[key], theirs[key]);
+    if (pick.conflict) {
+      conflicts.push({
+        scope: 'envelope',
+        identity: key,
+        base: base[key],
+        ours: ours[key],
+        theirs: theirs[key],
+      });
+      merged[key] = ours[key];
+      continue;
+    }
+    if (pick.value !== undefined) merged[key] = pick.value;
+  }
+  return { merged, conflicts };
+}
+
+/**
+ * 3-way merge two baseline envelopes against their common ancestor.
+ *
+ * @param {{
+ *   base: object|null,
+ *   ours: object,
+ *   theirs: object,
+ *   kind?: string,
+ *   components?: Array<object>,
+ * }} params
+ *   - `base` — the merge ancestor; `null` (or a rowless object) when the
+ *     file was added on both sides.
+ *   - `components` — passed straight to the kind's `rollup()`. Defaults to
+ *     `[]`, which is what `refreshBaseline` effectively uses, so a merged
+ *     envelope carries the same `{'*': …}` rollup shape a refresh writes.
+ * @returns {{
+ *   kind: string,
+ *   envelope: object,
+ *   conflicts: Array<{scope: string, identity: string, base?: unknown, ours?: unknown, theirs?: unknown}>,
+ * }}
+ */
+export function mergeEnvelopes({
+  base,
+  ours,
+  theirs,
+  kind,
+  components = [],
+} = {}) {
+  const resolvedKind =
+    kind ?? kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
+  if (!resolvedKind) {
+    throw new Error(
+      'mergeEnvelopes: could not resolve a known baseline kind from the envelopes',
+    );
+  }
+  const mod = getKindModule(resolvedKind);
+  const baseEnv = base && typeof base === 'object' ? base : { rows: [] };
+
+  const baseRows = indexRows(baseEnv.rows, mod.rowIdentity, 'base');
+  const ourRows = indexRows(ours?.rows, mod.rowIdentity, 'ours');
+  const theirRows = indexRows(theirs?.rows, mod.rowIdentity, 'theirs');
+
+  const conflicts = [];
+  const rows = [];
+  const identities = new Set([
+    ...ourRows.keys(),
+    ...theirRows.keys(),
+    ...baseRows.keys(),
+  ]);
+  for (const id of identities) {
+    const b = baseRows.get(id);
+    const o = ourRows.get(id);
+    const t = theirRows.get(id);
+    const pick = choose(b, o, t);
+    if (pick.conflict) {
+      conflicts.push({
+        scope: 'row',
+        identity: id,
+        base: b,
+        ours: o,
+        theirs: t,
+      });
+      // Keep the ours-side value so the row set stays well-formed; the
+      // driver renders the conflict markers around it from this record.
+      if (o !== undefined) rows.push(o);
+      else if (t !== undefined) rows.push(t);
+      continue;
+    }
+    if (pick.value !== undefined) rows.push(pick.value);
+  }
+
+  const sortedRows = mod.sortRows(rows);
+  const { merged: stamps, conflicts: stampConflicts } = mergeStamps(
+    baseEnv,
+    ours ?? {},
+    theirs ?? {},
+  );
+
+  const envelope = {
+    ...stamps,
+    generatedAt: laterStamp(ours?.generatedAt, theirs?.generatedAt),
+    rollup: mod.rollup(sortedRows, components),
+    rows: sortedRows,
+  };
+
+  return {
+    kind: resolvedKind,
+    envelope,
+    conflicts: [...stampConflicts, ...conflicts],
+  };
+}