mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/audit-baselines/engine.js

@@ -0,0 +1,177 @@
+/**
+ * engine.js — assemble the `/audit-baselines` evidence envelope
+ * (Story #4902).
+ *
+ * Strictly read-only and strictly offline: it reads committed baselines, the
+ * resolved config, git history, the static import graph, and any friction
+ * ledger it finds. It never writes under `baselines/`, never refreshes a
+ * baseline, and never runs a test, coverage, or mutation suite — the whole
+ * point is that a baseline review costs a file read, not a CI run.
+ *
+ * Findings are evidence, not a verdict: assembling the envelope is success,
+ * however alarming its contents, so the CLI exits 0 whenever it got this far.
+ * Judgment belongs to the lens that reads the envelope.
+ *
+ * @module lib/audit-baselines/engine
+ */
+
+import path from 'node:path';
+import { mainCheckoutRoot, tempRootFrom } from '../config/temp-paths.js';
+import { getQuality, resolveConfig } from '../config-resolver.js';
+import { buildGateSurface } from './gate-surface.js';
+import { buildHeadroom } from './headroom.js';
+import { buildHotspots } from './hotspots.js';
+import { ALL_KINDS, baselinePathFor, GATE_KINDS } from './kinds.js';
+import { DEFAULT_TOP_N, extractOutliers } from './outliers.js';
+import { buildTrend } from './trend.js';
+import {
+  makeWeightResolver,
+  readCentrality,
+  readChurn,
+  readFriction,
+} from './weights.js';
+
+/** Envelope `kind` discriminator; matches the shipped schema's const. */
+const ENVELOPE_KIND = 'audit-baselines-envelope';
+
+/** Envelope schema version — bumped on any breaking shape change. */
+const ENVELOPE_SCHEMA_VERSION = '1';
+
+/** Cap on emitted hotspot clusters, independent of the per-gate `topN`. */
+export const DEFAULT_HOTSPOT_LIMIT = 50;
+
+/**
+ * Resolve the repository config without letting a broken `.agentrc.json`
+ * abort the run — an unreadable config still leaves the baseline files
+ * themselves readable at their default paths.
+ *
+ * @param {string} cwd
+ * @returns {{ quality: object, configError: string | null }}
+ */
+function resolveQualityBlock(cwd) {
+  try {
+    return { quality: getQuality(resolveConfig({ cwd })), configError: null };
+  } catch (err) {
+    return { quality: { gates: {} }, configError: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Absolute temp root the friction ledger is searched under, anchored to the
+ * **analysed** repository rather than the process cwd. `resolvedTempRoot()`
+ * anchors to whichever checkout the current process sits in, which is the
+ * right answer for a writer and the wrong one here: an engine pointed at
+ * another repo with `--cwd` must read that repo's ledger, not this one's.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+function tempRootFor(cwd) {
+  let relative = 'temp';
+  try {
+    relative = tempRootFrom(resolveConfig({ cwd }));
+  } catch {
+    // Unreadable config — the framework default root is still worth probing.
+  }
+  if (path.isAbsolute(relative)) return relative;
+  return path.join(mainCheckoutRoot(cwd) ?? cwd, relative);
+}
+
+/**
+ * Run the engine and return the envelope object. Pure with respect to the
+ * filesystem apart from the reads named in the module docstring — writing
+ * the result is the caller's job.
+ *
+ * @param {{
+ *   cwd: string,
+ *   topN?: number,
+ *   hotspotLimit?: number,
+ *   trendDepth?: number,
+ *   now?: Date,
+ * }} args
+ * @returns {object} the `audit-baselines-envelope`
+ */
+export function runEngine({
+  cwd,
+  topN = DEFAULT_TOP_N,
+  hotspotLimit = DEFAULT_HOTSPOT_LIMIT,
+  trendDepth = 5,
+  now = new Date(),
+}) {
+  const { quality, configError } = resolveQualityBlock(cwd);
+  const { entries, baselines } = buildGateSurface({ cwd, quality, now });
+
+  const outliers = ALL_KINDS.flatMap((kind) =>
+    extractOutliers({ kind, baseline: baselines.get(kind) ?? null, topN }),
+  );
+
+  const churn = readChurn({ cwd });
+  const centrality = readCentrality({ cwd });
+  const friction = readFriction({ tempRootAbs: tempRootFor(cwd) });
+
+  return {
+    kind: ENVELOPE_KIND,
+    schemaVersion: ENVELOPE_SCHEMA_VERSION,
+    generatedAt: now.toISOString(),
+    cwd,
+    topN,
+    configError,
+    degradations: {
+      gitHistory: churn.degraded,
+      importGraph: centrality.degraded,
+      frictionLedger: friction.degraded,
+    },
+    gateSurface: entries,
+    hotspots: buildHotspots({
+      outliers,
+      weightsFor: makeWeightResolver({ churn, centrality, friction }),
+      limit: hotspotLimit,
+    }),
+    trend: buildTrend({
+      cwd,
+      kinds: ALL_KINDS,
+      pathFor: (kind) => baselinePathFor(kind, quality),
+      depth: trendDepth,
+    }),
+    headroom: buildHeadroom({ kinds: GATE_KINDS, quality, baselines }),
+  };
+}
+
+/**
+ * Condense an envelope into the pure-JSON stdout summary. Small enough to
+ * read in a terminal, and never carrying a row set.
+ *
+ * @param {object} envelope
+ * @param {string} outPath absolute path the full envelope was written to
+ * @returns {object}
+ */
+export function summarize(envelope, outPath) {
+  return {
+    kind: 'audit-baselines-summary',
+    schemaVersion: ENVELOPE_SCHEMA_VERSION,
+    out: outPath,
+    generatedAt: envelope.generatedAt,
+    gateSurface: {
+      total: envelope.gateSurface.length,
+      configured: envelope.gateSurface.filter((g) => g.configured).length,
+      missingBaseline: envelope.gateSurface
+        .filter((g) => !g.baselineExists)
+        .map((g) => g.kind),
+      stubs: envelope.gateSurface.filter((g) => g.stub).map((g) => g.kind),
+      deadIgnoreGlobs: envelope.gateSurface.reduce(
+        (n, g) => n + g.deadIgnoreGlobs.length,
+        0,
+      ),
+    },
+    hotspots: {
+      total: envelope.hotspots.length,
+      multiGate: envelope.hotspots.filter((h) => h.gateCount > 1).length,
+      top: envelope.hotspots
+        .slice(0, 5)
+        .map((h) => ({ path: h.path, gates: h.gateKinds, rank: h.rank })),
+    },
+    trend: { kinds: envelope.trend.length },
+    headroom: { axes: envelope.headroom.length },
+    degradations: envelope.degradations,
+  };
+}

package/.agents/scripts/lib/audit-baselines/gate-surface.js

@@ -0,0 +1,63 @@
+/**
+ * gate-surface.js — walk both halves of the baseline surface (Story #4902).
+ *
+ * The closed `delivery.quality.gates` kinds and the out-of-band ratchet
+ * baselines are one surface, and an engine that walks only the first silently
+ * drops the second. This module owns that walk and the file universe an
+ * `ignoreGlobs` entry is checked against; [`surface-entry.js`](surface-entry.js)
+ * turns each kind into its health report.
+ *
+ * @module lib/audit-baselines/gate-surface
+ */
+
+import path from 'node:path';
+import { ALL_KINDS, baselinePathFor, GATE_KINDS } from './kinds.js';
+import { listFilesUnder, readJsonFile } from './read.js';
+import { surfaceEntryFor } from './surface-entry.js';
+
+/**
+ * Every `targetDirs` entry declared by any gate, deduplicated. This is the
+ * file universe an `ignoreGlobs` entry is checked against — a glob that
+ * matches nothing inside the dirs its own gate scans is dead weight.
+ *
+ * @param {object | null | undefined} quality
+ * @returns {string[]}
+ */
+function declaredTargetDirs(quality) {
+  const dirs = new Set();
+  for (const kind of GATE_KINDS) {
+    for (const dir of quality?.gates?.[kind]?.targetDirs ?? []) {
+      if (typeof dir === 'string' && dir.length > 0) dirs.add(dir);
+    }
+  }
+  return [...dirs].sort();
+}
+
+/**
+ * Walk both halves of the gate surface — the closed `delivery.quality.gates`
+ * kinds and the out-of-band ratchet baselines — and report each instrument's
+ * health.
+ *
+ * @param {{ cwd: string, quality: object, now?: Date, run?: Function }} args
+ *   `run` overrides the git spawn; `staleness.js` owns the real default.
+ * @returns {{ entries: object[], baselines: Map<string, object|null> }}
+ *   `baselines` carries each parsed envelope forward so the hotspot, trend,
+ *   and headroom sections never re-read a 650KB file off disk.
+ */
+export function buildGateSurface({ cwd, quality, now = new Date(), run }) {
+  const files = declaredTargetDirs(quality).flatMap((dir) =>
+    listFilesUnder(cwd, dir),
+  );
+  const io = { cwd, run };
+  const entries = [];
+  const baselines = new Map();
+  for (const kind of ALL_KINDS) {
+    const relPath = baselinePathFor(kind, quality);
+    const read = readJsonFile(path.resolve(cwd, relPath));
+    entries.push(
+      surfaceEntryFor({ kind, quality, read, relPath, files, now, io }),
+    );
+    baselines.set(kind, read.parsed);
+  }
+  return { entries, baselines };
+}

package/.agents/scripts/lib/audit-baselines/headroom.js

@@ -0,0 +1,72 @@
+/**
+ * headroom.js — how much slack sits between each configured floor and the
+ * number actually measured (Story #4902).
+ *
+ * A floor set far from reality is a gate that cannot fail. Headroom is the
+ * distance the measurement could still drift before the gate notices, and it
+ * is the direct input to the only remediation this lens ever recommends:
+ * tighten the floor to what the repo already achieves.
+ *
+ * Both sides come from the repository, never from this module: the floor
+ * from `resolveQuality()` over `.agentrc.json` (so a consumer's own floors
+ * are the ones reported), and the measurement from the committed baseline's
+ * whole-repo rollup. Polarity comes from `axisDirection` in the gate's own
+ * floors phase, so "better" always means the same thing here as it does when
+ * `check-baselines.js` decides pass or fail.
+ *
+ * @module lib/audit-baselines/headroom
+ */
+
+import { axisDirection } from '../orchestration/check-baselines/phases/floors.js';
+import { rollupOf } from './kinds.js';
+
+/**
+ * Signed distance from the floor, positive when the measurement sits on the
+ * good side of it. Null when the baseline carries no value for the axis.
+ *
+ * @param {number | undefined} measured
+ * @param {number} floor
+ * @param {'gte' | 'lte'} direction
+ * @returns {number | null}
+ */
+function headroomFor(measured, floor, direction) {
+  if (typeof measured !== 'number') return null;
+  return direction === 'gte' ? measured - floor : floor - measured;
+}
+
+/**
+ * Build the `headroom[]` section across every configured gate kind.
+ *
+ * @param {{
+ *   kinds: string[],
+ *   quality: object,
+ *   baselines: Map<string, object | null>,
+ * }} args
+ * @returns {Array<object>}
+ */
+export function buildHeadroom({ kinds, quality, baselines }) {
+  const out = [];
+  for (const kind of kinds) {
+    const floors = quality?.gates?.[kind]?.floors?.['*'];
+    if (!floors || typeof floors !== 'object') continue;
+    const rollup = rollupOf(baselines.get(kind) ?? null);
+    for (const [axis, floor] of Object.entries(floors)) {
+      if (typeof floor !== 'number' || !Number.isFinite(floor)) continue;
+      const measured = rollup?.[axis];
+      const direction = axisDirection(kind, axis);
+      out.push({
+        kind,
+        axis,
+        floor,
+        measured: typeof measured === 'number' ? measured : null,
+        direction,
+        // Positive headroom = the measurement is on the good side of the
+        // floor by this much; negative = the floor is already breached.
+        headroom: headroomFor(measured, floor, direction),
+      });
+    }
+  }
+  return out.sort(
+    (a, b) => a.kind.localeCompare(b.kind) || a.axis.localeCompare(b.axis),
+  );
+}

package/.agents/scripts/lib/audit-baselines/hotspots.js

@@ -0,0 +1,69 @@
+/**
+ * hotspots.js — join per-gate outliers into ranked, per-file clusters
+ * (Story #4902).
+ *
+ * The signal a baseline review is looking for is *convergence*: the file that
+ * is simultaneously a CRAP outlier, a maintainability outlier, and a
+ * duplication outlier is a different kind of problem from three unrelated
+ * files each bad at one thing. Reading the baselines one at a time cannot see
+ * it, because each gate's own top-20 is a different list.
+ *
+ * So severity **adds across gate memberships** and the three cost
+ * multipliers apply to the sum. Two gate memberships of severity s therefore
+ * outrank one membership of severity s at equal churn, centrality, and
+ * friction — which is the ranking property this section exists to provide.
+ *
+ * @module lib/audit-baselines/hotspots
+ */
+
+/**
+ * Group per-gate outlier rows by cluster id and rank them.
+ *
+ * @param {{
+ *   outliers: Array<object>,
+ *   weightsFor: (id: string) => {
+ *     churnWeight: number, centralityWeight: number, frictionWeight: number,
+ *   },
+ *   limit?: number,
+ * }} args
+ * @returns {Array<object>} highest rank first
+ */
+export function buildHotspots({ outliers, weightsFor, limit = 50 }) {
+  const clusters = new Map();
+  for (const row of outliers) {
+    let cluster = clusters.get(row.id);
+    if (!cluster) {
+      cluster = { path: row.id, gates: [], severityWeight: 0 };
+      clusters.set(row.id, cluster);
+    }
+    cluster.gates.push({
+      kind: row.kind,
+      metric: row.metric,
+      value: row.value,
+      rowCount: row.rowCount,
+      severityWeight: row.severityWeight,
+    });
+    cluster.severityWeight += row.severityWeight;
+  }
+
+  const ranked = [];
+  for (const cluster of clusters.values()) {
+    const weights = weightsFor(cluster.path);
+    cluster.gates.sort((a, b) => a.kind.localeCompare(b.kind));
+    ranked.push({
+      path: cluster.path,
+      gates: cluster.gates,
+      gateKinds: cluster.gates.map((g) => g.kind),
+      gateCount: cluster.gates.length,
+      severityWeight: cluster.severityWeight,
+      ...weights,
+      rank:
+        cluster.severityWeight *
+        weights.churnWeight *
+        weights.centralityWeight *
+        weights.frictionWeight,
+    });
+  }
+  ranked.sort((a, b) => b.rank - a.rank || a.path.localeCompare(b.path));
+  return ranked.slice(0, Math.max(0, limit));
+}

package/.agents/scripts/lib/audit-baselines/kinds.js

@@ -0,0 +1,313 @@
+/**
+ * kinds.js — the two halves of the gate surface, and how to read a row out
+ * of each (Story #4902).
+ *
+ * Mandrel's baseline surface is not one list. `delivery.quality.gates` is a
+ * **closed** AJV schema of eight kinds, enforced by `check-baselines.js`.
+ * Alongside it sit out-of-band **ratchet** baselines — dead exports (two
+ * passes), import cycles, context budget — which no gate block declares and
+ * only the CI baselines job runs. An engine that walks one half and calls it
+ * "the baselines" silently drops the other; both halves are enumerated here.
+ *
+ * `GATE_KINDS` is derived from `GATES_SCHEMA` rather than re-typed, so a
+ * ninth gate kind landing in the schema reaches this engine automatically.
+ *
+ * @module lib/audit-baselines/kinds
+ */
+
+import { GATES_SCHEMA } from '../config/gates/index.js';
+
+/** The closed `delivery.quality.gates` kind set, in stable order. */
+export const GATE_KINDS = Object.freeze(
+  Object.keys(GATES_SCHEMA.properties).sort(),
+);
+
+/**
+ * Out-of-band ratchet baselines: committed under `baselines/` and enforced
+ * only by the CI baselines job, never by `check-baselines.js`.
+ */
+const RATCHET_KINDS = Object.freeze([
+  'arch-cycles',
+  'context-budget',
+  'cyclomatic',
+  'dead-exports',
+  'dead-exports-production',
+]);
+
+/** Every kind the engine walks, gates first then ratchets. */
+export const ALL_KINDS = Object.freeze([...GATE_KINDS, ...RATCHET_KINDS]);
+
+/**
+ * Resolve a kind's baseline path from config, falling back to the framework
+ * default layout. Never hardcodes a consumer's location: a repo that moved
+ * `baselines/crap.json` via `gates.crap.baselinePath` is followed.
+ *
+ * @param {string} kind
+ * @param {object | null | undefined} quality resolved `delivery.quality`
+ * @returns {string} repo-relative path
+ */
+export function baselinePathFor(kind, quality) {
+  const configured = quality?.gates?.[kind]?.baselinePath;
+  if (typeof configured === 'string' && configured.length > 0) {
+    return configured;
+  }
+  return `baselines/${kind}.json`;
+}
+
+/**
+ * Flatten `context-budget.json` into `{ id, value }` rows. Its three
+ * sections all measure the same axis (bytes of context a file costs) under
+ * different keys, so they fold into one row set rather than three.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function contextBudgetRows(baseline) {
+  const out = [];
+  for (const tier of Object.values(baseline?.tiers ?? {})) {
+    for (const f of tier?.files ?? []) out.push({ id: f.path, value: f.bytes });
+  }
+  for (const f of baseline?.agentBoot?.files ?? []) {
+    out.push({ id: f.path, value: f.bytes });
+  }
+  for (const e of baseline?.workflowClosure?.entryPoints ?? []) {
+    out.push({ id: e.path, value: e.reachableBytes });
+  }
+  return out.filter(
+    (r) => typeof r.id === 'string' && Number.isFinite(r.value),
+  );
+}
+
+/**
+ * Count how many allowlisted cycles each module participates in. A module in
+ * three cycles is a worse architectural hotspot than one in a single cycle.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function archCycleRows(baseline) {
+  const counts = new Map();
+  for (const cycle of baseline?.cycles ?? []) {
+    for (const member of new Set(cycle ?? [])) {
+      counts.set(member, (counts.get(member) ?? 0) + 1);
+    }
+  }
+  return [...counts].map(([id, value]) => ({ id, value }));
+}
+
+/**
+ * Count dead exports per file. The row grain is `{ file, symbol }`; the
+ * hotspot grain is the file.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function deadExportRows(baseline) {
+  const counts = new Map();
+  for (const row of baseline?.rows ?? []) {
+    if (typeof row?.file !== 'string') continue;
+    counts.set(row.file, (counts.get(row.file) ?? 0) + 1);
+  }
+  return [...counts].map(([id, value]) => ({ id, value }));
+}
+
+/**
+ * Build the `{ id, value }` extractor for an envelope-shaped gate kind.
+ *
+ * @param {string} idKey row property carrying the cluster identity
+ * @param {string} metric row property carrying the measured value
+ * @returns {(baseline: object) => Array<{ id: string, value: number }>}
+ */
+function envelopeRows(idKey, metric) {
+  return (baseline) =>
+    (baseline?.rows ?? [])
+      .map((row) => ({ id: row?.[idKey], value: row?.[metric] }))
+      .filter((r) => typeof r.id === 'string' && Number.isFinite(r.value));
+}
+
+/**
+ * Fold `{ id, value }` rows into one whole-repo number.
+ *
+ * `TOTAL` is for **additive** metrics — dead-export symbols, context bytes,
+ * lint errors — where the sum is the quantity the instrument measures.
+ * `TALLY` is for **non-additive** ones — percentages, indices, scores — where
+ * summing per-file values would fabricate a statistic; the honest whole-repo
+ * number is how many rows are tracked, and the unit name says so.
+ */
+const TOTAL = (rows) => rows.reduce((sum, row) => sum + row.value, 0);
+const TALLY = (rows) => rows.length;
+
+/**
+ * `[unit, fold]` per kind: the unit each kind's whole-repo total is
+ * denominated in, and how its rows fold into it.
+ *
+ * This is the fix for the roll-up that counted **files** for every kind
+ * (Story #4962). `dead-exports-production` moving 590 → 589 *symbols* across
+ * 187 files on both sides read as a delta of 0, and a 421-byte context-budget
+ * growth read as 0 too, because the fallback counted rows — a grain finer than
+ * the file for dead exports and coarser than the byte for context budget.
+ * Naming the unit is half the fix: an axis called `symbols` or `bytes` cannot
+ * be re-read as a file count the way a bare `rowCount` was.
+ */
+const TREND_UNITS = Object.freeze({
+  'bundle-size': ['rawKb', TOTAL],
+  coverage: ['filesTracked', TALLY],
+  crap: ['filesTracked', TALLY],
+  duplication: ['filesTracked', TALLY],
+  lighthouse: ['routesTracked', TALLY],
+  lint: ['errorCount', TOTAL],
+  maintainability: ['filesTracked', TALLY],
+  mutation: ['filesTracked', TALLY],
+  'arch-cycles': ['cycleMemberships', TOTAL],
+  'context-budget': ['bytes', TOTAL],
+  cyclomatic: ['filesTracked', TALLY],
+  'dead-exports': ['symbols', TOTAL],
+  'dead-exports-production': ['symbols', TOTAL],
+});
+
+/**
+ * Per-kind row spec.
+ *
+ * - `metric`  — the axis a hotspot is measured on.
+ * - `worse`   — which end of that axis is the bad end.
+ * - `rows`    — baseline → `{ id, value }` pairs, already aggregated where
+ *               the on-disk grain is finer than the file (dead exports,
+ *               cycles).
+ * - `idKind`  — what the cluster key names. Every kind but `lighthouse`
+ *               (routes) and `bundle-size` (bundle names) keys on a
+ *               repository file path.
+ */
+export const KIND_SPECS = Object.freeze({
+  'bundle-size': {
+    metric: 'rawKb',
+    worse: 'higher',
+    idKind: 'bundle',
+    rows: envelopeRows('bundle', 'rawKb'),
+  },
+  coverage: {
+    metric: 'lines',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'lines'),
+  },
+  crap: {
+    metric: 'crap',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'crap'),
+  },
+  duplication: {
+    metric: 'percentage',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'percentage'),
+  },
+  lighthouse: {
+    metric: 'performance',
+    worse: 'lower',
+    idKind: 'route',
+    rows: envelopeRows('route', 'performance'),
+  },
+  lint: {
+    metric: 'errorCount',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'errorCount'),
+  },
+  maintainability: {
+    metric: 'mi',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'mi'),
+  },
+  mutation: {
+    metric: 'score',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'score'),
+  },
+  'arch-cycles': {
+    metric: 'cycleMemberships',
+    worse: 'higher',
+    idKind: 'path',
+    rows: archCycleRows,
+  },
+  'context-budget': {
+    metric: 'bytes',
+    worse: 'higher',
+    idKind: 'path',
+    rows: contextBudgetRows,
+  },
+  cyclomatic: {
+    metric: 'maxCyclomatic',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('file', 'maxCyclomatic'),
+  },
+  'dead-exports': {
+    metric: 'deadExports',
+    worse: 'higher',
+    idKind: 'path',
+    rows: deadExportRows,
+  },
+  'dead-exports-production': {
+    metric: 'deadExports',
+    worse: 'higher',
+    idKind: 'path',
+    rows: deadExportRows,
+  },
+});
+
+/**
+ * The whole-repo rollup for a kind, or `null` when the kind does not carry
+ * one. Ratchet baselines have no rollup — which is why stub detection asks
+ * for an all-zero rollup rather than merely empty rows: an `arch-cycles`
+ * baseline with zero cycles is a passing gate, not a dead instrument.
+ *
+ * @param {object | null} baseline
+ * @returns {object | null}
+ */
+export function rollupOf(baseline) {
+  const rollup = baseline?.rollup?.['*'];
+  return rollup && typeof rollup === 'object' ? rollup : null;
+}
+
+/**
+ * The whole-repo quantity a kind measures, in the unit it measures it in —
+ * `{ unit, value }`, or `null` when the kind or the baseline is unreadable.
+ *
+ * This sits beside `rowCount` in `gateSurface[]` precisely because the two
+ * disagree: `dead-exports-production` carries 589 rows across 187 files, so a
+ * lone `rowCount: 187` reads as a symbol count and is not one.
+ *
+ * @param {string} kind
+ * @param {object | null} baseline
+ * @returns {{ unit: string, value: number } | null}
+ */
+export function measuredTotalOf(kind, baseline) {
+  const spec = KIND_SPECS[kind];
+  const denomination = TREND_UNITS[kind];
+  if (!baseline || !spec || !denomination) return null;
+  const [unit, fold] = denomination;
+  return { unit, value: fold(spec.rows(baseline)) };
+}
+
+/**
+ * The rollup a trend sample compares on. Gate kinds carry their own, already
+ * axis-named; ratchet baselines carry none, so the whole-repo total stands in
+ * under its own unit — "dead exports went 590 → 589 **symbols**" is exactly
+ * the direction-of-travel question trend answers, and skipping the ratchet
+ * half here would leave it visible in `gateSurface[]` but invisible in
+ * `trend[]`.
+ *
+ * @param {string} kind
+ * @param {object | null} baseline
+ * @returns {object | null}
+ */
+export function trendRollupOf(kind, baseline) {
+  if (!baseline) return null;
+  const declared = rollupOf(baseline);
+  if (declared) return declared;
+  const measured = measuredTotalOf(kind, baseline);
+  return measured ? { [measured.unit]: measured.value } : null;
+}