mandrel 1.57.0

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -0,0 +1,129 @@
+/**
+ * env-overrides.js — pure resolvers for the per-kind baseline env overrides.
+ *
+ * Hoisted from `check-crap.js` and `check-maintainability.js` (Story #1981,
+ * Task #1989) so the env-precedence behavior — config → env → default,
+ * malformed values warn-and-fall-through — lives in a lib module the
+ * per-kind callers (and tests) can share without spawning a CLI.
+ *
+ * No I/O. No side effects beyond logger warnings.
+ */
+
+import { Logger } from '../Logger.js';
+
+// Framework default MI tolerance. Raised from 0.001 to 0.5 because real-world
+// noise (Node-version churn, escomplex internal updates, typhonjs-escomplex
+// rounding) routinely drifts +/- 0.05 to 0.3 on otherwise-unchanged files —
+// well below the threshold of "actually less maintainable." A 0.5 floor
+// stops the pre-push hook from auto-ratcheting the baseline on noise.
+export const MI_DEFAULT_TOLERANCE = 0.5;
+
+/**
+ * Pure helper: resolve the effective CRAP config by layering env-var
+ * overrides on top of the resolved `.agentrc.json` values. Exported so
+ * tests can assert the precedence + malformed-value behavior without
+ * spawning the CLI.
+ *
+ * @param {{ newMethodCeiling?: unknown, tolerance?: unknown, refreshTag?: unknown }} crapConfig
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ newMethodCeiling: number, tolerance: number, refreshTag: string, overrides: string[] }}
+ */
+export function resolveCrapEnvOverrides(crapConfig, env) {
+  const overrides = [];
+  let newMethodCeiling = Number.isFinite(crapConfig?.newMethodCeiling)
+    ? crapConfig.newMethodCeiling
+    : 30;
+  // Default 0.05 (raised from 0.001 in 5.36.1). CRAP scores are
+  // `c² · (1 − cov)³ + c`, so a sub-percent per-method coverage rounding
+  // shift across CI environments — same code, different escomplex /
+  // coverage build — moves the score by ~0.01 on its own. A 0.001
+  // tolerance flagged that as a regression; real regressions cross
+  // whole-integer thresholds (e.g. 8 → 12) and clear 0.05 trivially.
+  let tolerance = Number.isFinite(crapConfig?.tolerance)
+    ? crapConfig.tolerance
+    : 0.05;
+  let refreshTag =
+    typeof crapConfig?.refreshTag === 'string' && crapConfig.refreshTag.length
+      ? crapConfig.refreshTag
+      : 'baseline-refresh:';
+
+  const rawCeiling = env?.CRAP_NEW_METHOD_CEILING;
+  if (rawCeiling !== undefined && rawCeiling !== '') {
+    const parsed = Number(rawCeiling);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      newMethodCeiling = parsed;
+      overrides.push(`newMethodCeiling=${parsed} (CRAP_NEW_METHOD_CEILING)`);
+    } else {
+      Logger.warn(
+        `[CRAP] ⚠ ignoring malformed CRAP_NEW_METHOD_CEILING=${rawCeiling}; keeping config value ${newMethodCeiling}`,
+      );
+    }
+  }
+
+  const rawTolerance = env?.CRAP_TOLERANCE;
+  if (rawTolerance !== undefined && rawTolerance !== '') {
+    const parsed = Number(rawTolerance);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      tolerance = parsed;
+      overrides.push(`tolerance=${parsed} (CRAP_TOLERANCE)`);
+    } else {
+      Logger.warn(
+        `[CRAP] ⚠ ignoring malformed CRAP_TOLERANCE=${rawTolerance}; keeping config value ${tolerance}`,
+      );
+    }
+  }
+
+  const rawRefreshTag = env?.CRAP_REFRESH_TAG;
+  if (typeof rawRefreshTag === 'string' && rawRefreshTag.length > 0) {
+    refreshTag = rawRefreshTag;
+    overrides.push(`refreshTag=${rawRefreshTag} (CRAP_REFRESH_TAG)`);
+  }
+
+  return { newMethodCeiling, tolerance, refreshTag, overrides };
+}
+
+/**
+ * Pure helper: resolve the effective MI tolerance by layering precedence:
+ *   1. `CRAP_TOLERANCE` env-var (CI override — the baseline-refresh-
+ *      guardrail uses this to force base-branch values on both gates).
+ *   2. `delivery.quality.gates.maintainability.tolerance` from the config.
+ *   3. `MI_DEFAULT_TOLERANCE` (0.5).
+ *
+ * Malformed env values warn and fall through to the next layer — a typo
+ * in CI must never silently relax the gate, but it also must not skip the
+ * configured project value.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{ tolerance?: number }} [maintainabilityConfig]
+ * @returns {{ tolerance: number, overrides: string[] }}
+ */
+export function resolveMaintainabilityEnvOverrides(env, maintainabilityConfig) {
+  const overrides = [];
+  let tolerance = MI_DEFAULT_TOLERANCE;
+  // Layer 2: config value (lower precedence than env, higher than default).
+  const configured = maintainabilityConfig?.tolerance;
+  if (
+    typeof configured === 'number' &&
+    Number.isFinite(configured) &&
+    configured >= 0
+  ) {
+    tolerance = configured;
+    overrides.push(
+      `tolerance=${configured} (quality.maintainability.tolerance)`,
+    );
+  }
+  // Layer 1: env override (highest precedence).
+  const raw = env?.CRAP_TOLERANCE;
+  if (raw !== undefined && raw !== '') {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      tolerance = parsed;
+      overrides.push(`tolerance=${parsed} (CRAP_TOLERANCE)`);
+    } else {
+      Logger.warn(
+        `[Maintainability] ⚠ ignoring malformed CRAP_TOLERANCE=${raw}; keeping ${tolerance}`,
+      );
+    }
+  }
+  return { tolerance, overrides };
+}

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

@@ -0,0 +1,368 @@
+/**
+ * envelope.js — assemble and validate baseline envelopes (Story #1891,
+ * Epic #1786).
+ *
+ * Every committed Mandrel baseline ships an envelope-shaped JSON with five
+ * top-level keys:
+ *
+ *   {
+ *     "$schema": ".agents/schemas/baselines/<kind>.schema.json",
+ *     "kernelVersion": "<semver>",
+ *     "generatedAt": "<ISO-8601>",
+ *     "rollup":  { "*": { ... }, [component]: { ... } },
+ *     "rows":    [ ... ]
+ *   }
+ *
+ * The envelope contract is declared in
+ * `.agents/schemas/baselines/baseline-envelope.schema.json` and the
+ * per-kind schemas extend it via `allOf` (Story #1888).
+ *
+ * This module exposes:
+ *
+ *   buildEnvelope({ kind, rollup, rows, kernelVersion, generatedAt? })
+ *     Stamps `$schema`, `kernelVersion`, and `generatedAt` onto a freshly
+ *     constructed envelope. When `generatedAt` is omitted, the
+ *     `MANDREL_BASELINE_GENERATED_AT` env var overrides any other clock
+ *     reading — this lets reproducible-build tests pin the timestamp
+ *     without monkey-patching `Date`. When neither is provided, the
+ *     envelope stamps `new Date().toISOString()`.
+ *
+ *   assertEnvelope(envelope)
+ *     Compiles every per-kind schema once (AJV) and validates the envelope
+ *     against the schema named in its `$schema`. Throws on schema
+ *     mismatch, missing top-level keys, or a `$schema` that doesn't
+ *     correspond to one of the seven known per-kind schemas.
+ *
+ * The writer (`writer.js`) calls `buildEnvelope` then `assertEnvelope`
+ * before serialising — so every baseline written through the shared
+ * pipeline is schema-valid by construction.
+ *
+ * @module lib/baselines/envelope
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Repo-relative `.agents/schemas/baselines/` directory. Resolved off the
+ * module URL so the envelope works the same in the main checkout, in a
+ * worktree, and inside CI's bare clone — none of those have a stable
+ * `process.cwd()` relative to the schemas.
+ */
+const SCHEMAS_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'baselines',
+);
+
+/**
+ * Canonical list of kinds the shared envelope supports. The writer's
+ * per-kind module list lives in `kinds/index.js`; this constant is the
+ * envelope's view of the same set, kept here to break the import cycle
+ * (`kinds/<kind>` imports envelope; envelope only needs the names).
+ */
+export const KNOWN_KINDS = Object.freeze([
+  'lint',
+  'coverage',
+  'crap',
+  'maintainability',
+  'mutation',
+  'lighthouse',
+  'bundle-size',
+  'duplication',
+]);
+
+function schemaRefFor(kind) {
+  return `.agents/schemas/baselines/${kind}.schema.json`;
+}
+
+function kernelVersionPattern() {
+  return /^[0-9]+\.[0-9]+\.[0-9]+$/;
+}
+
+function isoTimestampPattern() {
+  // RFC 3339 / ISO 8601 with optional fractional seconds and a `Z` or
+  // `±HH:MM` offset. AJV's `date-time` format does the heavy validation;
+  // this is a cheap pre-check so we can throw a friendlier error before
+  // AJV ever runs.
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+}
+
+/**
+ * Resolve the effective `generatedAt` for an envelope. Priority:
+ *
+ *   1. Caller-supplied `generatedAt`.
+ *   2. `MANDREL_BASELINE_GENERATED_AT` env var (reproducible-build hook).
+ *   3. `new Date().toISOString()`.
+ *
+ * Validates the resulting string against an ISO-8601 shape and throws a
+ * clear error if it doesn't match — operators get the failure at write
+ * time, not when AJV runs.
+ *
+ * @param {string|undefined} explicit
+ * @returns {string}
+ */
+function resolveGeneratedAt(explicit) {
+  const candidate =
+    typeof explicit === 'string' && explicit.length > 0
+      ? explicit
+      : (process.env.MANDREL_BASELINE_GENERATED_AT ?? new Date().toISOString());
+  if (typeof candidate !== 'string' || !isoTimestampPattern().test(candidate)) {
+    throw new Error(
+      `envelope.buildEnvelope: generatedAt must be an ISO-8601 timestamp (got ${JSON.stringify(candidate)})`,
+    );
+  }
+  return candidate;
+}
+
+/**
+ * Construct an envelope. The caller supplies the per-kind row + rollup
+ * shape; this module stamps the envelope-level keys.
+ *
+ * @param {{
+ *   kind: string,
+ *   rollup: Record<string, object>,
+ *   rows: Array<object>,
+ *   kernelVersion: string,
+ *   generatedAt?: string,
+ * }} params
+ * @returns {{
+ *   $schema: string,
+ *   kernelVersion: string,
+ *   generatedAt: string,
+ *   rollup: Record<string, object>,
+ *   rows: Array<object>,
+ * }}
+ */
+export function buildEnvelope({
+  kind,
+  rollup,
+  rows,
+  kernelVersion,
+  generatedAt,
+} = {}) {
+  if (typeof kind !== 'string' || !KNOWN_KINDS.includes(kind)) {
+    throw new TypeError(
+      `envelope.buildEnvelope: kind must be one of ${KNOWN_KINDS.join(', ')} (got ${JSON.stringify(kind)})`,
+    );
+  }
+  if (
+    typeof kernelVersion !== 'string' ||
+    !kernelVersionPattern().test(kernelVersion)
+  ) {
+    throw new TypeError(
+      `envelope.buildEnvelope: kernelVersion must be semver-shaped (got ${JSON.stringify(kernelVersion)})`,
+    );
+  }
+  if (!rollup || typeof rollup !== 'object' || Array.isArray(rollup)) {
+    throw new TypeError(
+      'envelope.buildEnvelope: rollup must be an object keyed by component',
+    );
+  }
+  if (!Object.hasOwn(rollup, '*')) {
+    throw new Error(
+      'envelope.buildEnvelope: rollup["*"] (whole-repo rollup) is required',
+    );
+  }
+  if (!Array.isArray(rows)) {
+    throw new TypeError('envelope.buildEnvelope: rows must be an array');
+  }
+
+  return {
+    $schema: schemaRefFor(kind),
+    kernelVersion,
+    generatedAt: resolveGeneratedAt(generatedAt),
+    rollup,
+    rows,
+  };
+}
+
+/**
+ * Lazy AJV instance — compiled schemas are memoised so successive writes
+ * during a single Node process don't re-compile the seven schemas.
+ */
+let _ajv = null;
+const _validators = new Map();
+
+function getAjv() {
+  if (_ajv) return _ajv;
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const envelopeSchema = JSON.parse(
+    fs.readFileSync(
+      path.join(SCHEMAS_DIR, 'baseline-envelope.schema.json'),
+      'utf8',
+    ),
+  );
+  ajv.addSchema(envelopeSchema, 'baseline-envelope.schema.json');
+  _ajv = ajv;
+  return ajv;
+}
+
+function getValidator(kind) {
+  if (_validators.has(kind)) return _validators.get(kind);
+  const ajv = getAjv();
+  const schema = JSON.parse(
+    fs.readFileSync(path.join(SCHEMAS_DIR, `${kind}.schema.json`), 'utf8'),
+  );
+  const validate = ajv.compile(schema);
+  _validators.set(kind, validate);
+  return validate;
+}
+
+/**
+ * The five top-level keys every envelope MUST carry. Pre-checked before
+ * AJV runs so the error names the missing key directly instead of
+ * surfacing as an AJV "required" violation.
+ */
+const REQUIRED_TOP_LEVEL_KEYS = Object.freeze([
+  '$schema',
+  'kernelVersion',
+  'generatedAt',
+  'rollup',
+  'rows',
+]);
+
+// ---------------------------------------------------------------------------
+// Shared baseline compatibility axes (Story #2467, Task #2492).
+//
+// Every baseline-kind compatibility check shares the same universal
+// invariants: the envelope must exist, its kernelVersion must match the
+// running scorer, and (when published) its `generatedAt` must be monotonic
+// vs the running clock. Per-kind axis tables (e.g. `CRAP_COMPAT_AXES`)
+// compose these into their kind-specific axis list so the hoisted axes
+// live in exactly one place.
+//
+// Each axis exposes `{ name, severity, check }`:
+//   - `name`     — stable label used as `kind` in the failure envelope.
+//   - `severity` — `'fatal'` (short-circuit, exitCode 1) or `'warn'`
+//                  (accumulate into `warnings`).
+//   - `check`    — pure function over the compat context. Returns `null`
+//                  when the axis passes, or a string message describing
+//                  the failure.
+// ---------------------------------------------------------------------------
+
+/**
+ * Universal "missing baseline" axis. Fires when the loader returned `null`
+ * / `undefined`. The operator message is parametrised by the kind label
+ * supplied at composition time so each kind keeps its own bootstrap hint.
+ *
+ * @param {string} kindLabel — operator-facing label (e.g. `CRAP`, `MI`).
+ * @returns {{name: string, severity: 'fatal', check: (ctx: {baseline: unknown}) => string|null}}
+ */
+export function missingBaselineAxis(kindLabel) {
+  return {
+    name: 'missing-baseline',
+    severity: 'fatal',
+    check: ({ baseline }) =>
+      baseline === null || baseline === undefined
+        ? `[${kindLabel}] ❌ no baseline found — run the matching baseline-update command and commit with a 'baseline-refresh:' subject to bootstrap`
+        : null,
+  };
+}
+
+/**
+ * Universal "kernel-version drift" axis. Fires when the baseline's
+ * recorded `kernelVersion` differs from the running scorer's
+ * `kernelVersion`. Warn-only by default — kernel drift surfaces as a
+ * baseline-refresh nudge, not a close-validation failure.
+ *
+ * @param {string} kindLabel
+ * @returns {{name: string, severity: 'warn', check: (ctx: {baseline: {kernelVersion?: string}|null|undefined, runningKernelVersion: string}) => string|null}}
+ */
+export function kernelDriftAxis(kindLabel) {
+  return {
+    name: 'kernel-drift',
+    severity: 'warn',
+    check: ({ baseline, runningKernelVersion }) =>
+      baseline && baseline.kernelVersion !== runningKernelVersion
+        ? `[${kindLabel}] ⚠ kernelVersion drift: baseline=${baseline.kernelVersion} running=${runningKernelVersion}. ` +
+          "Run the matching baseline-update command and commit with a 'baseline-refresh:' subject to refresh."
+        : null,
+  };
+}
+
+/**
+ * Reduce an axis list against a compat context, emitting either a fatal
+ * envelope `{ ok: false, exitCode: 1, kind, message }` (on the first
+ * 'fatal' match) or an accumulating `{ ok: true, warnings }` envelope.
+ *
+ * Shared by every per-kind `evaluateBaselineCompatibility` caller so the
+ * reduce body lives in one place and stays well below the project's
+ * cyclomatic-complexity ceiling.
+ *
+ * @template {object} Ctx
+ * @param {Array<{name: string, severity: 'fatal'|'warn', check: (ctx: Ctx) => string|null}>} axes
+ * @param {Ctx} ctx
+ * @returns {{ok: true, warnings: string[]} | {ok: false, exitCode: 1, kind: string, message: string}}
+ */
+export function reduceCompatAxes(axes, ctx) {
+  return axes.reduce(
+    (acc, axis) => {
+      if (!acc.ok) return acc;
+      const message = axis.check(ctx);
+      if (!message) return acc;
+      if (axis.severity === 'fatal') {
+        return { ok: false, exitCode: 1, kind: axis.name, message };
+      }
+      acc.warnings.push(message);
+      return acc;
+    },
+    { ok: true, warnings: [] },
+  );
+}
+
+/**
+ * Validate an envelope against its per-kind schema.
+ *
+ * Two-phase check:
+ *   1. Cheap structural pre-check — every top-level key present, `$schema`
+ *      points at one of the seven known kinds. Throws with a clear
+ *      message when violated.
+ *   2. AJV schema validation against the per-kind schema named in `$schema`.
+ *      Throws with the AJV error list serialised as JSON.
+ *
+ * @param {object} envelope
+ * @returns {void}
+ * @throws {Error}
+ */
+export function assertEnvelope(envelope) {
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
+    throw new TypeError('envelope.assertEnvelope: expected an object envelope');
+  }
+  for (const key of REQUIRED_TOP_LEVEL_KEYS) {
+    if (!Object.hasOwn(envelope, key)) {
+      throw new Error(
+        `envelope.assertEnvelope: missing required top-level key "${key}"`,
+      );
+    }
+  }
+  const schemaRef = envelope.$schema;
+  if (typeof schemaRef !== 'string') {
+    throw new Error(
+      'envelope.assertEnvelope: $schema must be a string pointing at a per-kind schema',
+    );
+  }
+  const match = schemaRef.match(/baselines\/([^/]+)\.schema\.json$/);
+  if (!match || !KNOWN_KINDS.includes(match[1])) {
+    throw new Error(
+      `envelope.assertEnvelope: $schema "${schemaRef}" does not point at one of the known kinds (${KNOWN_KINDS.join(', ')})`,
+    );
+  }
+  const kind = match[1];
+  const validate = getValidator(kind);
+  const ok = validate(envelope);
+  if (!ok) {
+    throw new Error(
+      `envelope.assertEnvelope: ${kind} envelope failed schema validation: ${JSON.stringify(validate.errors)}`,
+    );
+  }
+}

package/.agents/scripts/lib/baselines/exit-codes.js

@@ -0,0 +1,89 @@
+// .agents/scripts/lib/baselines/exit-codes.js
+//
+// Story #1962 / Task #1968 — Unified exit-code contract for the baseline
+// dispatcher (`check-baselines.js`) and every per-kind regression CLI that
+// will land in Epic #1943.
+//
+// One shared source of truth keeps the dispatcher, the per-kind CLIs, and
+// the test suites in lock-step. Numeric precedence is intentional: a
+// higher number is a strictly worse outcome, so `aggregate(...)` collapses
+// per-gate exit codes by taking the maximum. That contract lets the
+// dispatcher fan out per-kind work in any order (parallel, sequential,
+// streamed) and still produce a single deterministic process exit code.
+//
+// Precedence (lowest → highest severity):
+//
+//   0 EXIT_PASS        — every enabled gate is green.
+//   1 EXIT_FLOOR       — at least one gate breached its floor / tolerance.
+//   2 EXIT_SCHEMA      — at least one baseline file failed schema
+//                        validation (JSON shape / required fields wrong).
+//   3 EXIT_CONFIG      — config could not be resolved (missing
+//                        `.agentrc.json`, unknown gate kind, malformed
+//                        scope, etc). The gate could not even start.
+//   4 EXIT_REGRESSION  — head-vs-base regression detected on at least one
+//                        gate. Highest severity because regression
+//                        signals new debt being introduced rather than
+//                        pre-existing debt failing a static floor.
+//
+// `aggregate(...codes)` takes the highest code in the input list and
+// returns 0 (`EXIT_PASS`) for an empty input. It never throws — invalid
+// codes are silently treated as 0 because the only sane response to a
+// caller passing a garbage code is "do not regress the exit signal".
+
+export const EXIT_PASS = 0;
+export const EXIT_FLOOR = 1;
+export const EXIT_SCHEMA = 2;
+export const EXIT_CONFIG = 3;
+export const EXIT_REGRESSION = 4;
+
+/**
+ * The full set of valid exit codes, frozen so callers can use it as a
+ * lookup without worrying about mutation.
+ */
+export const EXIT_CODES = Object.freeze({
+  EXIT_PASS,
+  EXIT_FLOOR,
+  EXIT_SCHEMA,
+  EXIT_CONFIG,
+  EXIT_REGRESSION,
+});
+
+const VALID = new Set([
+  EXIT_PASS,
+  EXIT_FLOOR,
+  EXIT_SCHEMA,
+  EXIT_CONFIG,
+  EXIT_REGRESSION,
+]);
+
+/**
+ * Collapse any number of per-gate exit codes into a single dispatcher
+ * exit code. The contract:
+ *
+ *   - With no arguments, returns `EXIT_PASS` (0). An empty dispatcher run
+ *     is success — there was nothing to fail.
+ *   - With one or more arguments, returns the maximum of the valid codes.
+ *     Higher numbers are strictly worse outcomes (see precedence table at
+ *     the top of this file).
+ *   - Unknown / non-numeric / negative codes are dropped from the input
+ *     so a single garbage caller cannot lower the dispatcher's exit code
+ *     past a real failure. If every input is invalid, the result is
+ *     `EXIT_PASS` (the caller signalled nothing to report).
+ *
+ * Pure. No I/O. Cheap to call from a hot loop.
+ *
+ * @param {...number} codes - Per-gate exit codes to collapse.
+ * @returns {number} The most severe code in the input, or `EXIT_PASS`.
+ */
+export function aggregate(...codes) {
+  let max = EXIT_PASS;
+  for (const c of codes) {
+    if (typeof c !== 'number' || !VALID.has(c)) {
+      continue;
+    }
+    if (c > max) {
+      max = c;
+    }
+  }
+  return max;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * kernel.js — per-kind kernel-version resolution (Story #1891, Epic #1786).
+ *
+ * Every committed baseline stamps a `kernelVersion` semver string in its
+ * envelope. The version tracks the in-repo (or upstream) kernel that
+ * produced the rows — a bump invalidates every committed baseline of
+ * that kind, signalling consumers to regenerate. The version source is
+ * **per-kind**:
+ *
+ *   - CRAP and Maintainability share the `typhonjs-escomplex` upstream
+ *     package version; both modules' `kernelVersion()` read it from the
+ *     nearest `node_modules/typhonjs-escomplex/package.json`.
+ *   - Lint, Coverage, Mutation, Lighthouse, Bundle-Size carry a static
+ *     in-repo semver bumped by hand whenever the scoring/rollup math
+ *     changes. Their `kernelVersion()` just returns the constant.
+ *
+ * This module is the public surface: callers ask
+ * `currentKernelVersion(kind)` and get a single string back, no matter
+ * which strategy the kind uses internally.
+ *
+ * `checkKernelVersion(kind, baselineVersion)` is the drift-detection
+ * helper. It returns `{ match, current }` so a CI gate can compare the
+ * baseline's stamp against the running kernel and decide whether to
+ * regenerate or fail.
+ *
+ * @module lib/baselines/kernel
+ */
+
+import * as bundleSize from './kinds/bundle-size.js';
+import * as coverage from './kinds/coverage.js';
+import * as crap from './kinds/crap.js';
+import * as duplication from './kinds/duplication.js';
+import * as lighthouse from './kinds/lighthouse.js';
+import * as lint from './kinds/lint.js';
+import * as maintainability from './kinds/maintainability.js';
+import * as mutation from './kinds/mutation.js';
+
+/**
+ * Registry of every shipped kind module. Keys mirror the per-kind schema
+ * filenames so a future "list all kinds" iterator can stay declarative.
+ */
+const KIND_MODULES = Object.freeze({
+  lint,
+  coverage,
+  crap,
+  maintainability,
+  mutation,
+  lighthouse,
+  'bundle-size': bundleSize,
+  duplication,
+});
+
+/**
+ * Look up a kind module by name. Throws when the kind isn't registered so
+ * callers can't silently fall through to undefined behaviour.
+ *
+ * @param {string} kind
+ * @returns {{ name: string, kernelVersion: () => string, keyField: string,
+ *           projectRow: (row: object) => object,
+ *           sortRows: (rows: object[]) => object[],
+ *           rollup: (rows: object[], components?: object[]) => object }}
+ */
+export function getKindModule(kind) {
+  const mod = KIND_MODULES[kind];
+  if (!mod) {
+    throw new Error(
+      `kernel.getKindModule: unknown kind "${kind}" (known: ${Object.keys(KIND_MODULES).join(', ')})`,
+    );
+  }
+  return mod;
+}
+
+/**
+ * Resolve the running kernel version for `kind`. Delegates to the per-kind
+ * module's `kernelVersion()` — see the module preamble for which strategy
+ * each kind uses.
+ *
+ * @param {string} kind
+ * @returns {string}
+ */
+export function currentKernelVersion(kind) {
+  return getKindModule(kind).kernelVersion();
+}
+
+/**
+ * Compare a baseline's stamped version against the currently running
+ * kernel for the same kind. Returns `{ match, current }` so callers can
+ * format a drift signal or trigger a regenerate.
+ *
+ * @param {string} kind
+ * @param {string} baselineVersion
+ * @returns {{ match: boolean, current: string }}
+ */
+export function checkKernelVersion(kind, baselineVersion) {
+  const current = currentKernelVersion(kind);
+  return {
+    match: baselineVersion === current,
+    current,
+  };
+}
+
+/**
+ * List every kind registered with the kernel. Useful for the writer's
+ * envelope sanity check and for tests that want to iterate all shipped
+ * kinds.
+ *
+ * @returns {string[]}
+ */
+export function listKinds() {
+  return Object.keys(KIND_MODULES);
+}