session-orchestrator 4.2.0 → 5.0.0

package/scripts/lib/ux-grill/run-record.mjs

@@ -0,0 +1,316 @@
+/**
+ * ux-grill/run-record.mjs — the ONLY reader/writer of the ux-grill run-record
+ * ledger (`.orchestrator/metrics/ux-grill.jsonl`) and of a run's `findings.jsonl`.
+ *
+ * Leaf-ish module: `node:fs` + `node:path` plus the two ux-grill leaf modules
+ * (`./paths.mjs`, `./schema.mjs`). No shell-outs, no network, no other project
+ * imports — so `compare.mjs` can depend on it without dragging a closure in.
+ *
+ * WHY a module and not `fs.appendFileSync` at each call site: the record is
+ * written ONCE by `collect()` with `compare` at its schema defaults
+ * (`{new:0, persisting:0, fixed:0}`) and PATCHED later by `compare.mjs`, after
+ * the previous run has been located. Two writers on one append-only file need a
+ * single place that knows (a) how a record is validated before it is appended,
+ * (b) that the patch is a line rewrite which must preserve line ORDER and every
+ * line it does not own, including unparseable ones.
+ *
+ * TOLERANT READS, COUNTED. Both readers skip a line they cannot parse and
+ * return how many they skipped, instead of throwing. A ledger is append-only
+ * telemetry that several processes write; one truncated line must not make the
+ * whole comparison impossible — but a silently-dropped line is exactly the
+ * "measurement over an unnamed population" trap, so the count is part of the
+ * return value and callers are expected to surface it.
+ *
+ * Exports:
+ *   appendRunRecord(repoRoot, record)
+ *   readRunRecords(repoRoot, {manifestHash, build, limit})
+ *   findPreviousRun(repoRoot, {manifestHash, build, beforeRunId})
+ *   updateRunRecordCompare(repoRoot, runId, compare)
+ *   readFindings(repoRoot, runId)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { findingsPath, runRecordPath } from './paths.mjs';
+import { makeRunRecord } from './schema.mjs';
+
+/** Default number of (filtered) records `readRunRecords` returns. */
+const DEFAULT_READ_LIMIT = 50;
+
+/**
+ * Read a UTF-8 file, returning `null` when it does not exist.
+ * Any other error (EACCES, EISDIR) propagates — that is a real defect, not an
+ * empty history, and must not read as "no previous run".
+ *
+ * @param {string} file
+ * @returns {string|null}
+ */
+function readTextOrNull(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * Parse a JSONL text blob into objects, counting the lines that did not parse.
+ *
+ * @param {string|null} text
+ * @param {(value: unknown) => boolean} isRecord - shape predicate; a parsed
+ *   line failing it counts as skipped, same as a syntax error.
+ * @returns {{values: object[], skippedLines: number}}
+ */
+function parseJsonl(text, isRecord) {
+  const values = [];
+  let skippedLines = 0;
+  if (text === null) return { values, skippedLines };
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (line.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      skippedLines += 1;
+      continue;
+    }
+    if (!isRecord(parsed)) {
+      skippedLines += 1;
+      continue;
+    }
+    values.push(parsed);
+  }
+  return { values, skippedLines };
+}
+
+/** A run-record is usable only when it carries the compare key: `run_id`. */
+function isRunRecord(value) {
+  return typeof value === 'object' && value !== null && typeof value.run_id === 'string';
+}
+
+/** A finding is usable only when it carries its identity: `fingerprint`. */
+function isFinding(value) {
+  return typeof value === 'object' && value !== null && typeof value.fingerprint === 'string';
+}
+
+/**
+ * Append ONE run-record to the ledger, creating the metrics directory if needed.
+ *
+ * The record is re-validated through {@link makeRunRecord} (required fields,
+ * `build` enum, `skipped[].reason` enum) but the ORIGINAL object is what gets
+ * written — re-validation must never silently re-default a field the caller
+ * set. Invalid input throws rather than appending a half-record: a ledger line
+ * nothing can parse is worse than a missing one, because the next reader counts
+ * it as `skippedLines` forever.
+ *
+ * This is the function `collect.mjs` calls (`collect.mjs:60` imports it, `:970`
+ * invokes it) — verified 2026-09-12, which is what makes the module header's
+ * "ONLY writer" claim true rather than aspirational.
+ *
+ * @param {string} repoRoot - absolute repo root of the TARGET repo
+ * @param {object} record - a record built by `makeRunRecord`
+ * @returns {object} the same record, for chaining
+ * @throws {TypeError} when the record fails schema validation
+ */
+export function appendRunRecord(repoRoot, record) {
+  if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+    throw new TypeError('appendRunRecord: record must be a plain object');
+  }
+  // Throws on any invalid required field; the return value is deliberately unused.
+  makeRunRecord({
+    runId: record.run_id,
+    manifestHash: record.manifest_hash,
+    rubricHash: record.rubric_hash,
+    build: record.build,
+    skipped: Array.isArray(record.skipped) ? record.skipped : [],
+    countsBySeverity: record.counts_by_severity,
+    provisionalCount: record.provisional_count,
+  });
+
+  const ledger = runRecordPath(repoRoot);
+  fs.mkdirSync(path.dirname(ledger), { recursive: true });
+  fs.appendFileSync(ledger, `${JSON.stringify(record)}\n`, 'utf8');
+  return record;
+}
+
+/**
+ * Read run-records from the ledger, newest LAST (file/append order preserved).
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts]
+ * @param {string} [opts.manifestHash] - keep only records with this `manifest_hash`
+ * @param {string} [opts.build] - keep only records with this `build`
+ * @param {number} [opts.limit=50] - keep at most this many of the MOST RECENT
+ *   matches (the tail of the filtered list). `Infinity` reads everything.
+ * @returns {{records: object[], skippedLines: number}} `skippedLines` counts
+ *   lines that were unparseable OR carried no `run_id`.
+ */
+export function readRunRecords(repoRoot, { manifestHash, build, limit = DEFAULT_READ_LIMIT } = {}) {
+  const { values, skippedLines } = parseJsonl(readTextOrNull(runRecordPath(repoRoot)), isRunRecord);
+  let records = values;
+  if (manifestHash !== undefined) records = records.filter((r) => r.manifest_hash === manifestHash);
+  if (build !== undefined) records = records.filter((r) => r.build === build);
+  if (Number.isFinite(limit) && limit >= 0 && records.length > limit) {
+    records = records.slice(records.length - limit);
+  }
+  return { records, skippedLines };
+}
+
+/**
+ * Find the run to compare the current run against.
+ *
+ * The baseline must share BOTH keys:
+ *   - `manifest_hash` — a different manifest measured different routes/viewports,
+ *     so a fingerprint missing from it was never looked for, not fixed.
+ *   - `build` — a dev build is not a measurement basis for a prod run (a dev
+ *     bundle's geometry differs, which is exactly why `makeFinding` marks
+ *     dev-build target-size findings `provisional`). Comparing across builds
+ *     would report layout noise as `new`/`fixed` product change.
+ *
+ * `rubric_hash` is deliberately NOT a filter: a rubric change must still be
+ * comparable, it only changes how `fixed` may be READ — see `compare.mjs`
+ * § rubricChanged.
+ *
+ * @param {string} repoRoot
+ * @param {object} opts
+ * @param {string} opts.manifestHash
+ * @param {string} opts.build
+ * @param {string} [opts.beforeRunId] - the CURRENT run; records from its ledger
+ *   line onward are ignored, so a run never compares against itself or against
+ *   a run appended after it.
+ * @returns {object|null} the most recent matching record, or `null` (baseline run)
+ */
+export function findPreviousRun(repoRoot, { manifestHash, build, beforeRunId } = {}) {
+  const { records } = readRunRecords(repoRoot, { limit: Infinity });
+  let scope = records;
+  if (typeof beforeRunId === 'string' && beforeRunId.length > 0) {
+    const index = records.findIndex((r) => r.run_id === beforeRunId);
+    if (index >= 0) scope = records.slice(0, index);
+  }
+  for (let i = scope.length - 1; i >= 0; i -= 1) {
+    const record = scope[i];
+    if (manifestHash !== undefined && record.manifest_hash !== manifestHash) continue;
+    if (build !== undefined && record.build !== build) continue;
+    return record;
+  }
+  return null;
+}
+
+/**
+ * Validate a compare-counts object: exactly three non-negative integers.
+ * @param {unknown} compare
+ * @returns {{new: number, persisting: number, fixed: number}}
+ * @throws {TypeError}
+ */
+function assertCompareCounts(compare) {
+  if (typeof compare !== 'object' || compare === null || Array.isArray(compare)) {
+    throw new TypeError('updateRunRecordCompare: compare must be a plain object');
+  }
+  const out = {};
+  for (const key of ['new', 'persisting', 'fixed']) {
+    const value = compare[key];
+    if (!Number.isInteger(value) || value < 0) {
+      throw new TypeError(`updateRunRecordCompare: compare.${key} must be a non-negative integer, got ${String(value)}`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Patch the `compare` counts of ONE already-appended run-record, in place.
+ *
+ * Rewrites the ledger atomically (tmp file in the same directory + `rename`) so
+ * a crash mid-write cannot leave a truncated ledger. Line ORDER is preserved and
+ * every line this call does not own is written back BYTE-IDENTICALLY, including
+ * lines that do not parse — a repair pass must never be the thing that destroys
+ * the evidence it was reading (the raw-sidecar lesson, one layer up).
+ *
+ * The record carries COUNTS, never the fingerprint lists — that is the schema
+ * (`makeRunRecord` § compare). The lists stay in the caller's hands.
+ *
+ * BV-004 — deliberate simplification, its CEILING and its REVISIT TRIGGER:
+ * this is a WHOLE-LEDGER rewrite (read every line, re-serialise the one that
+ * matches, `rename` the lot) rather than a seek-and-patch. Ceiling: fine while
+ * `.orchestrator/metrics/ux-grill.jsonl` stays under ~10k records — one record
+ * per `/ux-grill` run, i.e. years of routine use at a few runs per session.
+ * REVISIT TRIGGER: the ledger passing ~10k lines, or `/ux-grill` becoming a
+ * per-commit/CI step rather than an operator-invoked one. Either makes the
+ * rewrite O(n) per compare over a file nobody reads whole.
+ *
+ * CONCURRENCY — decided, not overlooked: this function takes NO lock, and a
+ * concurrent {@link appendRunRecord} landing between the read above and the
+ * `rename` below would be lost. That is accepted because ONE ux-grill run per
+ * repo is the only shape the surrounding design admits: Stufe 1 is a single
+ * coordinator-direct Bash call (`skills/ux-grill/SKILL.md` § 0.4 — "exactly one
+ * Bash invocation", "No dispatched agent runs Stufe 1"), and the compare step
+ * runs after it in the same thread. Taking `withFileLock` from
+ * `scripts/lib/file-lock.mjs` would additionally force this whole module async
+ * for a race the design forbids. REVISIT TRIGGER for the assumption: the first
+ * caller that runs `collect()` in parallel (multi-target sweep, CI matrix) —
+ * then use `withFileLock` here AND in `appendRunRecord`, never only one of them.
+ *
+ * @param {string} repoRoot
+ * @param {string} runId
+ * @param {{new: number, persisting: number, fixed: number}} compare
+ * @returns {{updated: number, skippedLines: number}} `updated` is how many
+ *   ledger lines matched `runId` (0 = the record is not in the ledger; the
+ *   caller decides whether that is an error).
+ * @throws {TypeError} on a malformed `compare`
+ */
+export function updateRunRecordCompare(repoRoot, runId, compare) {
+  const counts = assertCompareCounts(compare);
+  const ledger = runRecordPath(repoRoot);
+  const text = readTextOrNull(ledger);
+  if (text === null) return { updated: 0, skippedLines: 0 };
+
+  let updated = 0;
+  let skippedLines = 0;
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (raw.trim().length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      skippedLines += 1;
+      out.push(raw); // preserved verbatim — never dropped by a patch pass
+      continue;
+    }
+    if (isRunRecord(parsed) && parsed.run_id === runId) {
+      parsed.compare = { ...counts };
+      updated += 1;
+      out.push(JSON.stringify(parsed));
+      continue;
+    }
+    if (!isRunRecord(parsed)) skippedLines += 1;
+    out.push(raw);
+  }
+
+  const tmp = `${ledger}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, out.length > 0 ? `${out.join('\n')}\n` : '', 'utf8');
+  fs.renameSync(tmp, ledger);
+  return { updated, skippedLines };
+}
+
+/**
+ * Read one run's `findings.jsonl`.
+ *
+ * Returns an ENVELOPE rather than a bare array so the dropped-line count has
+ * somewhere to live (see module header): a compare run that silently lost three
+ * previous findings would report them as `fixed`.
+ *
+ * @param {string} repoRoot
+ * @param {string} runId
+ * @returns {{findings: object[], skippedLines: number}} `findings: []` when the
+ *   run produced none AND when the file does not exist — `skippedLines` does not
+ *   distinguish those; the caller that needs to tell them apart checks the run
+ *   record's `skipped[]`, which is what that field is for.
+ */
+export function readFindings(repoRoot, runId) {
+  const { values, skippedLines } = parseJsonl(readTextOrNull(findingsPath(repoRoot, runId)), isFinding);
+  return { findings: values, skippedLines };
+}

package/scripts/lib/ux-grill/schema.mjs

@@ -0,0 +1,321 @@
+/**
+ * ux-grill/schema.mjs — Frozen contract for Stufe-1 (mechanical) ux-grill records.
+ *
+ * Leaf module: imports only `../test-runner/fingerprint.mjs` and the pure
+ * `../crypto-digest-utils.mjs` (no I/O, no side effects; `node:crypto` reaches
+ * it only through that helper). Every producer of a ux-grill finding or run-record
+ * (`collect.mjs`, `measures.mjs`, `compare.mjs`) goes through this module so the
+ * fingerprint inputs and the severity table have exactly one definition.
+ *
+ * Spec: docs/prd/2026-09-12-ux-grill.md § 2 S2/S3 and § 4 Data Model.
+ *
+ * Exports:
+ *   SCOPE, CHECK_IDS, SEVERITIES, SEVERITY_BY_CHECK, SKIP_REASONS,
+ *   RUN_RECORD_SCHEMA_VERSION, LOCATOR_MAX_LENGTH,
+ *   severityForAxeImpact(), makeFinding(), countBySeverity(), makeRunRecord()
+ */
+
+import { digestSha256Short } from '../crypto-digest-utils.mjs';
+import { fingerprintFinding } from '../test-runner/fingerprint.mjs';
+
+/**
+ * Fingerprint scope for every ux-grill finding. Constant by contract: it is a
+ * fingerprint input, so changing it invalidates every previously filed issue.
+ * @type {string}
+ */
+export const SCOPE = 'ux-grill';
+
+/**
+ * The check identifiers ux-grill Stufe 1 can emit (PRD § 2 S3 table).
+ *
+ * `axe-violations` is the CATALOGUE entry only — an emitted axe finding carries
+ * `checkId = 'axe-<ruleId>'` (rubric-v1 § Fingerprint), so that two axe rules
+ * violated on the same selector remain two distinct findings.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const CHECK_IDS = Object.freeze({
+  AXE_VIOLATIONS: 'axe-violations',
+  CONSOLE_ERRORS: 'console-errors',
+  JOURNEY_STEP_COUNT: 'journey-step-count',
+  JOURNEY_FAILED: 'journey-failed',
+  TARGET_SIZE_FLOOR: 'target-size-floor',
+  TARGET_SIZE_TARGET: 'target-size-target',
+  HORIZONTAL_OVERFLOW: 'horizontal-overflow',
+  TITLE_MISMATCH: 'title-mismatch',
+});
+
+/**
+ * Severities ux-grill Stufe 1 emits, most severe first.
+ *
+ * Note: `skills/test-runner/rubric-v1.md` additionally knows `critical` for
+ * issue routing. Stufe 1 of ux-grill NEVER emits `critical` — every severity
+ * here is derived from a measured value (PRD § 2 S3), and no measured ux
+ * violation is defined as release-blocking. Stufe 2 emits no severity at all.
+ * @type {readonly string[]}
+ */
+export const SEVERITIES = Object.freeze(['high', 'medium', 'low']);
+
+/**
+ * Static severity per check id (PRD § 2 S3). Axe is absent by design — its
+ * severity comes from the impact field, see {@link severityForAxeImpact}.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const SEVERITY_BY_CHECK = Object.freeze({
+  [CHECK_IDS.TARGET_SIZE_FLOOR]: 'high',
+  [CHECK_IDS.TARGET_SIZE_TARGET]: 'medium',
+  [CHECK_IDS.HORIZONTAL_OVERFLOW]: 'medium',
+  [CHECK_IDS.JOURNEY_FAILED]: 'high',
+  [CHECK_IDS.JOURNEY_STEP_COUNT]: 'medium',
+  [CHECK_IDS.CONSOLE_ERRORS]: 'medium',
+  [CHECK_IDS.TITLE_MISMATCH]: 'low',
+});
+
+/**
+ * Reasons a Stufe-1 step may be recorded as skipped in the run-record.
+ *
+ * - `device-mismatch`  — `set device` / `set viewport` did not produce the
+ *   requested `window.innerWidth`; the viewport is skipped rather than filed
+ *   under a wrong label (PRD § 3 AC "Stufe 1").
+ * - `pencil-unavailable` — Pen.app or its MCP surface is not reachable; the
+ *   optional coverage step is skipped and the run still ends without error.
+ * - `route-unreachable` — the route failed to load. It is a SKIP, not a
+ *   dropped route: a route that never loaded produced no measurement, so
+ *   emitting zero findings for it would read as "clean" in the next compare
+ *   run and silently turn an outage into a `fixed` classification. Also used
+ *   for a journey whose `start` page never opened.
+ * - `measure-failed` — ONE browser measurement on an otherwise reachable page
+ *   did not produce a usable payload: a non-zero exit, an unparseable stdout,
+ *   or an `agent-browser` envelope carrying `success: false` (measured
+ *   2026-09-12, v0.37.1: a page-side `eval` throw answers `{"success":false,
+ *   "data":null,...}` at EXIT CODE 0). Without this reason such a call is
+ *   indistinguishable from "measured, found nothing" — zero findings for a
+ *   check that never ran, which the next compare run reads as `fixed`.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const SKIP_REASONS = Object.freeze({
+  DEVICE_MISMATCH: 'device-mismatch',
+  PENCIL_UNAVAILABLE: 'pencil-unavailable',
+  ROUTE_UNREACHABLE: 'route-unreachable',
+  MEASURE_FAILED: 'measure-failed',
+});
+
+/**
+ * Schema version of the `.orchestrator/metrics/ux-grill.jsonl` run-record.
+ * @type {number}
+ */
+export const RUN_RECORD_SCHEMA_VERSION = 1;
+
+/**
+ * Locators longer than this are truncated in the finding RECORD
+ * (`skills/test-runner/rubric-v1.md` § Truncation rule for long locators).
+ *
+ * Deliberate deviation from rubric-v1 for the FINGERPRINT input (#1334): an
+ * over-long locator is fingerprinted as `truncated + ':' + sha256(full).slice(0, 8)`,
+ * not as the bare truncation. The audited page controls its selectors, so with
+ * bare truncation a decoy under a >256-char class chain sharing the real
+ * element's prefix would take its fingerprint and shadow it in `compare.mjs`.
+ * Locators of ≤ 256 chars keep their fingerprint unchanged; the suffixed input
+ * is 265 chars long, so it can never equal an untruncated one.
+ * @type {number}
+ */
+export const LOCATOR_MAX_LENGTH = 256;
+
+/** Characters forbidden in a locator: they are the fingerprint separator / shell arg boundary. */
+const LOCATOR_FORBIDDEN = /[\n\r\0]/;
+
+const VALID_BUILDS = Object.freeze(['dev', 'prod']);
+
+/**
+ * Map an axe-core `impact` value to a ux-grill severity (PRD § 2 S3).
+ *
+ * @param {string} impact - axe impact: 'critical' | 'serious' | 'moderate' | 'minor'
+ * @returns {string} 'high' | 'medium' | 'low'. Unknown, missing or non-string
+ *   impacts default to `'low'` — an unclassifiable violation is reported but
+ *   never allowed to inflate the high band that drives automatic issue filing.
+ */
+export function severityForAxeImpact(impact) {
+  if (impact === 'critical' || impact === 'serious') return 'high';
+  if (impact === 'moderate') return 'medium';
+  return 'low';
+}
+
+/**
+ * Build a ux-grill finding record.
+ *
+ * The fingerprint is computed from `(SCOPE, checkId, truncatedLocator)` ONLY —
+ * never from severity, build, message or evidence, so that the same violation
+ * keeps its identity across runs and across dev/prod builds.
+ *
+ * @param {object} opts
+ * @param {string} opts.checkId - a value of {@link CHECK_IDS}, or `axe-<ruleId>`
+ *   for axe. Passing the literal `'axe-violations'` throws: two axe rules
+ *   violated on one selector must remain two findings, which only holds when the
+ *   rule id is part of the fingerprint input.
+ * @param {string} opts.locator - `route|viewport|selector` for route checks,
+ *   `journey|viewport|<name>` for journey checks. Must contain at least one `|`
+ *   and no newline/CR/NUL. Truncated to {@link LOCATOR_MAX_LENGTH} before
+ *   fingerprinting; the truncated form is what the record carries.
+ * @param {string} opts.severity - one of {@link SEVERITIES}.
+ * @param {string} opts.build - `'dev'` or `'prod'`; drives `provisional`.
+ * @param {string} [opts.message] - one-line human summary.
+ * @param {object} [opts.evidence] - free-form evidence pointers (screenshot
+ *   path, axe node, measured px). Defaults to `{}`.
+ * @returns {{scope: string, checkId: string, locator: string, severity: string,
+ *   provisional: boolean, fingerprint: string, message: string, evidence: object}}
+ * @throws {TypeError} on any invalid input — no silent defaults.
+ */
+export function makeFinding({ checkId, locator, severity, build, message, evidence } = {}) {
+  if (typeof checkId !== 'string' || checkId.length === 0) {
+    throw new TypeError('makeFinding: checkId must be a non-empty string');
+  }
+  // Same predicate as the locator check below. `checkId` is fingerprint input
+  // and is rendered into issue bodies and JSONL lines; a newline or NUL in it
+  // splits one record into two. Downstream `reconcile.oneLine()` contains it
+  // today, but the constructor is where a rejected input belongs (BV-002).
+  if (LOCATOR_FORBIDDEN.test(checkId)) {
+    throw new TypeError('makeFinding: checkId must not contain newline, CR or NUL');
+  }
+  if (checkId === CHECK_IDS.AXE_VIOLATIONS) {
+    throw new TypeError(
+      "makeFinding: checkId 'axe-violations' is the catalogue entry, not an emittable id — pass 'axe-<ruleId>' so two axe rules on one selector stay two findings",
+    );
+  }
+  if (typeof locator !== 'string' || locator.length === 0) {
+    throw new TypeError('makeFinding: locator must be a non-empty string');
+  }
+  if (!locator.includes('|')) {
+    throw new TypeError("makeFinding: locator must be pipe-delimited (route|viewport|selector or journey|viewport|<name>)");
+  }
+  if (LOCATOR_FORBIDDEN.test(locator)) {
+    throw new TypeError('makeFinding: locator must not contain newline, CR or NUL');
+  }
+  if (!SEVERITIES.includes(severity)) {
+    throw new TypeError(`makeFinding: severity must be one of ${SEVERITIES.join('|')}, got ${String(severity)}`);
+  }
+  if (!VALID_BUILDS.includes(build)) {
+    throw new TypeError(`makeFinding: build must be one of ${VALID_BUILDS.join('|')}, got ${String(build)}`);
+  }
+  if (message !== undefined && typeof message !== 'string') {
+    throw new TypeError('makeFinding: message must be a string when provided');
+  }
+  if (evidence !== undefined && (typeof evidence !== 'object' || evidence === null || Array.isArray(evidence))) {
+    throw new TypeError('makeFinding: evidence must be a plain object when provided');
+  }
+
+  const truncated = locator.slice(0, LOCATOR_MAX_LENGTH);
+  // See LOCATOR_MAX_LENGTH: only an over-long locator gets the full-text digest
+  // suffix, so ≤256-char fingerprints stay byte-for-byte stable.
+  const fingerprintLocator =
+    locator.length > LOCATOR_MAX_LENGTH ? `${truncated}:${digestSha256Short(locator)}` : truncated;
+  return {
+    scope: SCOPE,
+    checkId,
+    locator: truncated,
+    severity,
+    // Dev builds are not a geometry measurement basis (PRD § 2 S3), so
+    // target-size findings from a dev build are flagged rather than dropped.
+    provisional: build === 'dev' && checkId.startsWith('target-size-'),
+    fingerprint: fingerprintFinding({ scope: SCOPE, checkId, locator: fingerprintLocator }),
+    message: message ?? '',
+    evidence: evidence ?? {},
+  };
+}
+
+/**
+ * Count findings per severity band.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @returns {{high: number, medium: number, low: number}} zero-filled for every band.
+ * @throws {TypeError} if `findings` is not an array or carries an unknown severity.
+ */
+export function countBySeverity(findings) {
+  if (!Array.isArray(findings)) {
+    throw new TypeError('countBySeverity: findings must be an array');
+  }
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const finding of findings) {
+    const severity = finding?.severity;
+    if (!SEVERITIES.includes(severity)) {
+      throw new TypeError(`countBySeverity: unknown severity ${String(severity)}`);
+    }
+    counts[severity] += 1;
+  }
+  return counts;
+}
+
+/**
+ * Build the `.orchestrator/metrics/ux-grill.jsonl` run-record (PRD § 4).
+ *
+ * @param {object} opts
+ * @param {string} opts.runId - run identifier (see `paths.mjs` `makeRunId`).
+ * @param {string} opts.manifestHash - hash of the resolved ux-manifest; the
+ *   compare key — only runs with the same manifest_hash are comparable.
+ * @param {string} opts.rubricHash - hash of `skills/ux-grill/rubric-v2.md`.
+ * @param {string} opts.build - `'dev'` or `'prod'`.
+ * @param {string} [opts.timestamp] - ISO-8601 UTC; defaults to now.
+ * @param {string[]} [opts.viewports] - viewport labels actually run.
+ * @param {string[]} [opts.routes] - route paths actually run.
+ * @param {Array<{severity: string}>} [opts.findings] - drives `counts_by_severity`
+ *   and `provisional_count` when those are not passed explicitly.
+ * @param {{high: number, medium: number, low: number}} [opts.countsBySeverity]
+ * @param {number} [opts.provisionalCount]
+ * @param {{new: number, persisting: number, fixed: number}} [opts.compare]
+ * @param {Array<{what: string, reason: string}>} [opts.skipped] - `reason` must
+ *   be a value of {@link SKIP_REASONS}.
+ * @param {Array<{route: string, frame: string}>} [opts.pencilCoverage]
+ * @returns {object} the run-record, with exactly the PRD § 4 fields.
+ * @throws {TypeError} on missing/invalid required fields.
+ */
+export function makeRunRecord({
+  runId,
+  manifestHash,
+  rubricHash,
+  build,
+  timestamp,
+  viewports,
+  routes,
+  findings,
+  countsBySeverity,
+  provisionalCount,
+  compare,
+  skipped,
+  pencilCoverage,
+} = {}) {
+  for (const [name, value] of [
+    ['runId', runId],
+    ['manifestHash', manifestHash],
+    ['rubricHash', rubricHash],
+  ]) {
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new TypeError(`makeRunRecord: ${name} must be a non-empty string`);
+    }
+  }
+  if (!VALID_BUILDS.includes(build)) {
+    throw new TypeError(`makeRunRecord: build must be one of ${VALID_BUILDS.join('|')}, got ${String(build)}`);
+  }
+  const findingList = findings ?? [];
+  if (!Array.isArray(findingList)) {
+    throw new TypeError('makeRunRecord: findings must be an array when provided');
+  }
+  for (const entry of skipped ?? []) {
+    if (!Object.values(SKIP_REASONS).includes(entry?.reason)) {
+      throw new TypeError(`makeRunRecord: unknown skip reason ${String(entry?.reason)}`);
+    }
+  }
+
+  return {
+    schema_version: RUN_RECORD_SCHEMA_VERSION,
+    run_id: runId,
+    timestamp: timestamp ?? new Date().toISOString(),
+    manifest_hash: manifestHash,
+    rubric_hash: rubricHash,
+    build,
+    viewports: viewports ?? [],
+    routes: routes ?? [],
+    counts_by_severity: countsBySeverity ?? countBySeverity(findingList),
+    provisional_count: provisionalCount ?? findingList.filter((f) => f?.provisional).length,
+    compare: compare ?? { new: 0, persisting: 0, fixed: 0 },
+    skipped: skipped ?? [],
+    pencil_coverage: pencilCoverage ?? [],
+  };
+}