@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/utils/bizCiGateContract.js

@@ -6,6 +6,7 @@ const net = require('net');
 const { execSync } = require('child_process');
 const { readIntegrationRunArtefact } = require('./integrationRun');
 const { normalizeEnvDeclaration, collectEnvCoverage } = require('./envContract');
+const { normalizeStackTiersDeclaration } = require('./testCoverageContract');
 
 const CONNECTOR_KEYS = ['db', 'redis', 'mq', 'minio'];
 const DEFAULT_CONTRACT_RELATIVE_PATH = path.join('config', 'service', 'integration-contract.json');
@@ -47,6 +48,25 @@ function assertBoolean(value, fieldName) {
 const SCHEMA_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ENGINE_DECLARATION = /^(mariadb|mysql):[0-9][0-9.]*$/;
 
+/**
+ * The collation a service declares its schema is created with — owner decision
+ * 2026-09-14, `db-collation-declaration` 001, written into
+ * `docs/biz/70-contracts/database-contract.md` §1.
+ *
+ * Which utf8mb4 collation is the SERVICE's choice and this file sets none;
+ * what it holds is that the value is one, because it is interpolated into
+ * `CREATE DATABASE … COLLATE` the way `schema` is interpolated into the name,
+ * and because the platform speaks utf8mb4 end to end — the client is invoked
+ * with `--default-character-set=utf8mb4` (§3) and every permanent table of the
+ * eight repositories declares a utf8mb4 collation (measured 2026-09-14: 122 of
+ * 123, the exception being a table whose own thread has the finding).
+ *
+ * The key's PRESENCE is not this rail's question: a repository that declares
+ * none is reported by uniform row `D-DB-COLLATION`, and refused by
+ * `setupDatabase.buildSchema` before it builds anything.
+ */
+const COLLATION_DECLARATION = /^utf8mb4_[a-z0-9_]+$/;
+
 /** A declared path must stay inside the repository — it is resolved against the service root. */
 function assertRepoRelativePath(value, fieldName) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -85,6 +105,15 @@ function normalizeDatabaseDeclaration(database, connectors) {
       + 'Fix: use the real schema name, e.g. "oagen_emailer"; it is interpolated into CREATE DATABASE and USE.');
   }
 
+  if (database.collation !== undefined && !COLLATION_DECLARATION.test(
+    typeof database.collation === 'string' ? database.collation : ''
+  )) {
+    throw new Error(`[BizCiGate] Invalid database.collation - ${JSON.stringify(database.collation)} is not a `
+      + 'utf8mb4 collation name. Fix: declare the collation this service\'s schema is created with, e.g. '
+      + '"utf8mb4_bin" — the value is interpolated into CREATE DATABASE … COLLATE, and the platform speaks '
+      + 'utf8mb4 (api/docs/biz/70-contracts/database-contract.md §1).');
+  }
+
   assertRepoRelativePath(database.migrations, 'database.migrations');
 
   const seeds = database.seeds ?? [];
@@ -97,6 +126,7 @@ function normalizeDatabaseDeclaration(database, connectors) {
   return {
     engine: database.engine,
     schema: database.schema,
+    collation: database.collation,
     migrations: database.migrations,
     seeds
   };
@@ -139,6 +169,10 @@ function normalizeIntegrationContract(rawContract, contractPath, options = {}) {
 
   const database = normalizeDatabaseDeclaration(rawContract.database, normalizedConnectors);
   const env = normalizeEnvDeclaration(rawContract.env, { coverage: options.envCoverage });
+  // Which suites legitimately stand outside test:all, and why. The rules that
+  // read it live in utils/testCoverageContract.js; only the shape is decided here,
+  // beside the other declarations, so one file still answers "what may a contract say".
+  const stackTiers = normalizeStackTiersDeclaration(rawContract.stackTiers);
 
   return {
     serviceName: rawContract.serviceName || null,
@@ -148,6 +182,7 @@ function normalizeIntegrationContract(rawContract, contractPath, options = {}) {
     },
     database,
     env,
+    stackTiers,
     setup: rawContract.setup || {},
     raw: rawContract,
   };
@@ -240,9 +275,12 @@ function validatePackageScriptsForIntegrationMinimum(serviceRoot) {
     throw new Error('[BizCiGate] Missing package script - test:all is required');
   }
 
-  if (!/test:integration/.test(testAll)) {
-    throw new Error('[BizCiGate] Invalid test:all - must include test:integration');
-  }
+  // Whether test:all actually REACHES the integration tests is not asked here.
+  // It used to be, as a substring match on the script text — a rule about a name,
+  // which passed for `echo test:integration` and failed for a chain reaching the
+  // same files through another script. utils/testCoverageContract.js measures the
+  // fact instead: every file the jest config matches must be run by the test:all
+  // chain or declared as a stack tier (change-discipline.md § One rail per concern).
 
   return {
     packageJsonPath,
@@ -300,18 +338,100 @@ function formatEnvironmentOutput(env, format) {
   throw new Error(`[BizCiGate] Unsupported output format - ${format}`);
 }
 
+/**
+ * What the artefact says when a run declares a failure and names no step.
+ *
+ * It is not a filler string: it is the whole point of the change that put it
+ * here. "I do not know which step failed" is a true sentence somebody can act
+ * on; "integration minimum satisfied" beside a failing verdict is neither
+ * (`.claude/rules/truth-over-agreement.md` §4 — uncertainty is not certainty).
+ */
+const UNKNOWN_STEP_REASON = '[BizCiGate] unknown step failed - the run declared a failing verdict and '
+  + 'named no step, and the integration minimum (the only check this summary runs itself) is satisfied, '
+  + 'so nothing here can say what failed. Fix: pass the step from the CI job - '
+  + 'npm run ci:gate:summary -- --gate-verdict fail --gate-reason "<the step that exited non-zero>".';
+
+/**
+ * What the artefact says when a run declares `pass` over a check this summary
+ * measured as failing.
+ *
+ * It names the refusal rather than quietly correcting the verdict: the CI job
+ * asked for something it may not have, and whoever wrote that job is the only
+ * person who can stop asking. Format per
+ * `.claude/rules/architecture-principles.md` §5 - `[Context] Problem - Fix`.
+ *
+ * @param {string} measuredFailure the failing check's own message
+ * @returns {string}
+ */
+function refusedOverrideReason(measuredFailure) {
+  return '[BizCiGate] A measured failure cannot be declared passing - the integration minimum failed '
+    + `(${measuredFailure}) and the run passed --gate-verdict pass. The verdict stays fail: the override `
+    + 'exists to report a failure this summary cannot see for itself, never to withdraw one it can. '
+    + 'Fix: drop --gate-verdict pass from the ci:gate:summary call and make the integration minimum pass, '
+    + 'or correct integrationMinimum.minTestFiles in the integration contract if the requirement is wrong.';
+}
+
 function buildIntegrationSignalSummary(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
   const unitTestFiles = getUnitTestFiles(contractInfo.serviceRoot);
   const integrationTestFiles = getIntegrationTestFiles(contractInfo.serviceRoot);
 
-  let gateVerdict = options.gateVerdict || 'pass';
-  let gateReason = options.gateReason || 'integration minimum satisfied';
+  // The reason comes from the step that FAILED, or it admits it does not know
+  // which one did. Three sources, in this order, and no fourth:
+  //
+  //   1. the caller — the CI job watched the chain of ci:gate:* steps run and is
+  //      the only party that knows which of them exited non-zero;
+  //   2. the integration minimum, the one step this function runs itself, when
+  //      that is what failed;
+  //   3. nothing — and then the artefact says so.
+  //
+  // What it may never do is attribute somebody else's failure to the last check
+  // in the row. A job declaring `--gate-verdict fail` without a reason used to
+  // get "integration minimum satisfied" written beside a failing verdict, which
+  // is both untrue about the cause and an outright contradiction of the verdict
+  // beside it (reported twice by BIZ-ingest on 2026-09-08; the failing step had
+  // been setup-db both times).
+  // What this summary can establish ITSELF, before anybody declares anything.
+  let minimumFailure = null;
   try {
     verifyIntegrationMinimum(contractInfo.serviceRoot, contractInfo.contractPath);
   } catch (error) {
-    gateVerdict = options.gateVerdict || 'fail';
-    gateReason = options.gateReason || error.message;
+    minimumFailure = error.message;
+  }
+  const measuredVerdict = minimumFailure === null ? 'pass' : 'fail';
+
+  // `--gate-verdict` may only make the verdict WORSE. It exists so a job can
+  // report a failure this summary cannot see for itself - a step further up the
+  // chain that exited non-zero. Read the other way it is a bypass, and a gate
+  // has exactly one path and no flag that turns it off
+  // (`.claude/rules/automation-gates.md` §1 requirement 5).
+  const overrideRefused = options.gateVerdict === 'pass' && measuredVerdict === 'fail';
+  const gateVerdict = measuredVerdict === 'fail' || options.gateVerdict === 'fail' ? 'fail' : 'pass';
+
+  // The reason comes from the step that FAILED, or it admits it does not know
+  // which one did. Four sources, in this order, and no fifth:
+  //
+  //   0. the refusal above - a declared pass the measurement contradicts is
+  //      itself the thing the reader has to see, and neither the caller's own
+  //      reason nor the failure's message may stand in its place: "fail" beside
+  //      "test:all passed" is the same contradiction one step further on;
+  //   1. the caller - the CI job watched the chain of ci:gate:* steps run and is
+  //      the only party that knows which of them exited non-zero;
+  //   2. the integration minimum, the one step this function runs itself, when
+  //      that is what failed;
+  //   3. nothing - and then the artefact says so.
+  //
+  // What it may never do is attribute somebody else's failure to the last check
+  // in the row. A job declaring `--gate-verdict fail` without a reason used to
+  // get "integration minimum satisfied" written beside a failing verdict, which
+  // is both untrue about the cause and an outright contradiction of the verdict
+  // beside it (reported twice by BIZ-ingest on 2026-09-08; the failing step had
+  // been setup-db both times).
+  let gateReason = overrideRefused
+    ? refusedOverrideReason(minimumFailure)
+    : options.gateReason || minimumFailure;
+  if (!gateReason) {
+    gateReason = gateVerdict === 'pass' ? 'integration minimum satisfied' : UNKNOWN_STEP_REASON;
   }
 
   // Executed figures come from the run artefact or from nowhere. The previous
@@ -507,6 +627,10 @@ module.exports = {
   DEFAULT_CONTRACT_RELATIVE_PATH,
   loadAndValidateIntegrationContract,
   normalizeIntegrationContract,
+  // Exported so the consumers of a normalized `database` block can VERIFY they
+  // were handed one, against this definition and not a second copy of the shape
+  // (utils/installContract.js).
+  normalizeDatabaseDeclaration,
   getIntegrationTestFiles,
   getUnitTestFiles,
   verifyIntegrationMinimum,

package/src/utils/connectorContract.js

@@ -50,6 +50,96 @@ const CONNECTORS = {
   minio: { configSections: [], env: ['MINIO_ENDPOINT', 'MINIO_ACTUAL_HOST'] }
 };
 
+/** Where each of the two declarations lives, relative to the service root. */
+const CONFIG_PATH = 'config/service/config.json';
+const CONTRACT_PATH = 'config/service/integration-contract.json';
+
+/**
+ * Do the two declarations agree? — the half of the contract a CHECKOUT can
+ * answer, and therefore the half the uniform row `C-CONNECTORS` asks
+ * (confirmation `connector-contract-check` 001).
+ *
+ * It is separated from the environment half below for one reason: an
+ * environment is a property of a running container, not of a repository. The
+ * row runs from the api checkout and in CI, where no service's `REDIS_URL` is
+ * set and none should be — asking that question there would fail all eight
+ * services for a configuration none of them is running in, which is a gate
+ * whose violations have no fix (`automation-gates.md` §3).
+ *
+ * The RULE is stated once, in `mismatches()` below; this function and
+ * `verifyConnectorContract` are two phrasings of the same answer, for two
+ * surfaces (`change-discipline.md` § One rail per concern).
+ *
+ * @param {object} args
+ * @param {object} args.config parsed config/service/config.json
+ * @param {object} args.requiredConnectors from the integration contract
+ * @returns {{valid: boolean, checked: string[], findings: Array<{connector: string, where: string, what: string}>}}
+ *          `where` is the file that must change, `what` the contradiction —
+ *          the shape a manifest row reports, whose `fix` the row itself carries.
+ */
+function verifyConnectorDeclarations({ config, requiredConnectors }) {
+  const findings = mismatches({ config, requiredConnectors }).map((mismatch) => ({
+    connector: mismatch.connector,
+    where: mismatch.kind === 'required-not-configured' ? CONFIG_PATH : CONTRACT_PATH,
+    what: mismatch.kind === 'required-not-configured'
+      ? `requiredConnectors.${mismatch.connector} is true and no `
+        + `${mismatch.sections.map((section) => `wrapper.${section}`).join('/')} section configures it `
+        + '— the two declarations describe the same fact and one of them is wrong'
+      : `${CONFIG_PATH} configures wrapper.${mismatch.section} and requiredConnectors.${mismatch.connector} `
+        + 'is false — while they disagree, ci:gate:wait does not wait for this connector and the suite races it'
+  }));
+
+  return {
+    valid: findings.length === 0,
+    checked: requiredNames(requiredConnectors),
+    findings
+  };
+}
+
+/**
+ * The names the contract declares as required — what either half reports as
+ * "checked", so the two can never count differently.
+ *
+ * @param {object} requiredConnectors
+ * @returns {string[]}
+ */
+function requiredNames(requiredConnectors) {
+  return Object.keys(CONNECTORS).filter((name) => requiredConnectors?.[name] === true);
+}
+
+/**
+ * THE RULE, stated once: where the two declarations contradict each other.
+ *
+ * A connector with no `configSections` (db, minio) can contradict nothing here —
+ * no service on the platform declares a wrapper section for either, so both
+ * directions would be this module inventing a requirement. Their evidence is the
+ * environment, and that is the other half.
+ *
+ * @param {object} args
+ * @param {object} args.config parsed config/service/config.json
+ * @param {object} args.requiredConnectors from the integration contract
+ * @returns {Array<{connector: string, kind: string, sections?: string[], section?: string}>}
+ */
+function mismatches({ config, requiredConnectors }) {
+  const wrapper = config?.wrapper ?? {};
+  const found = [];
+
+  for (const [name, spec] of Object.entries(CONNECTORS)) {
+    if (spec.configSections.length === 0) continue;
+
+    const required = requiredConnectors?.[name] === true;
+    const section = spec.configSections.find((candidate) => wrapper[candidate] !== undefined);
+
+    if (required && section === undefined) {
+      found.push({ connector: name, kind: 'required-not-configured', sections: spec.configSections });
+    } else if (!required && section !== undefined) {
+      found.push({ connector: name, kind: 'configured-not-required', section });
+    }
+  }
+
+  return found;
+}
+
 /**
  * @param {object} args
  * @param {object} args.config parsed config/service/config.json
@@ -60,18 +150,18 @@ const CONNECTORS = {
 function verifyConnectorContract({ config, requiredConnectors, env }) {
   const errors = [];
   const checked = [];
-  const wrapper = config?.wrapper ?? {};
+  const byConnector = new Map(mismatches({ config, requiredConnectors }).map((m) => [m.connector, m]));
 
   for (const [name, spec] of Object.entries(CONNECTORS)) {
     const required = requiredConnectors?.[name] === true;
-    const configured = spec.configSections.some((section) => wrapper[section] !== undefined);
+    const mismatch = byConnector.get(name);
 
     if (required) {
       checked.push(name);
 
-      if (spec.configSections.length > 0 && !configured) {
+      if (mismatch !== undefined) {
         errors.push(`Connector "${name}" is required by the integration contract but no `
-          + `wrapper.${spec.configSections.join('/wrapper.')} section configures it in config/service/config.json.\n`
+          + `wrapper.${spec.configSections.join('/wrapper.')} section configures it in ${CONFIG_PATH}.\n`
           + `       Fix: configure it, or set requiredConnectors.${name} to false if the service does not use it.`);
       }
 
@@ -81,8 +171,8 @@ function verifyConnectorContract({ config, requiredConnectors, env }) {
           + '       Fix: set it in the CI job or config/env-active/*.env — a required connector without its '
           + 'endpoint fails later, inside the connector, where the cause is harder to see.');
       }
-    } else if (configured) {
-      errors.push(`config/service/config.json configures wrapper.${spec.configSections.find((s) => wrapper[s] !== undefined)} `
+    } else if (mismatch !== undefined) {
+      errors.push(`${CONFIG_PATH} configures wrapper.${mismatch.section} `
         + `but the integration contract says "${name}" is not required.\n`
         + '       The two declarations describe the same fact and must agree; while they disagree, '
         + 'ci:gate:wait does not wait for this connector and the suite races it.\n'
@@ -93,4 +183,4 @@ function verifyConnectorContract({ config, requiredConnectors, env }) {
   return { valid: errors.length === 0, checked, errors };
 }
 
-module.exports = { verifyConnectorContract, CONNECTORS };
+module.exports = { verifyConnectorContract, verifyConnectorDeclarations, CONNECTORS, CONFIG_PATH, CONTRACT_PATH };

package/src/utils/cookbookFormat.js

@@ -26,11 +26,32 @@
 /** Minimum accepted cookbook format version — format.md § Required fields. */
 const MIN_COOKBOOK_FORMAT_VERSION = '2.1.0';
 
-/** `major[.minor[.patch]]`, digits only — the shape format.md documents. */
-const VERSION_PATTERN = /^\d+(\.\d+){0,2}$/;
+/**
+ * `major.minor.patch`, digits only, all three components required.
+ *
+ * The machine SSOT is `shared/cookbook/cookbook-core/schemas/cookbook.v2.schema.json:16`
+ * — `"pattern": "^2\\.\\d+\\.\\d+$"`. Until 2026-09-05 this gate accepted 1 to 3
+ * components, so `"version": "2.1"` passed Tier-1 here and failed schema
+ * validation there: two rails, two answers, the offline one lenient. The major
+ * is deliberately NOT pinned to 2 here — that ceiling belongs to the schema; the
+ * floor this module owns is `MIN_COOKBOOK_FORMAT_VERSION`.
+ */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 
 const DOC_REFERENCE = 'api/docs/biz/40-cookbooks/format.md § Required fields';
 
+/**
+ * The same node, § The array is the only accepted shape — the section that owns
+ * both halves of the rule below: `steps` is an array, and a step identifies
+ * itself with `step_id`. The node has no section called `Steps`; this constant
+ * named one until 2026-09-14, and `L008` never noticed, because it checks the
+ * document and not the section behind `§`.
+ */
+const STEPS_DOC_REFERENCE = 'api/docs/biz/40-cookbooks/format.md § The array is the only accepted shape';
+
+/** `2.1` — how the format version is spoken about in prose, derived, never typed twice. */
+const MIN_FORMAT_MAJOR_MINOR = MIN_COOKBOOK_FORMAT_VERSION.split('.').slice(0, 2).join('.');
+
 /**
  * @param {string} version numeric version string, already pattern-checked
  * @returns {number[]} exactly three components, missing ones are 0
@@ -89,65 +110,86 @@ function checkCookbookFormatVersion(version) {
 }
 
 /**
- * Normalise a cookbook's `steps` into the array shape the rest of the package
- * works with, whichever of the two documented shapes it arrives in, and REFUSE
- * a step that spells its identifier `id`.
+ * @param {*} steps a `steps` value that is neither an array nor absent
+ * @returns {string} the shape, worded for the refusal message
+ */
+function describeStepsShape(steps) {
+  return typeof steps === 'object' ? 'an object' : `a ${typeof steps}`;
+}
+
+/**
+ * Read a cookbook's `steps` in the ONE shape the format allows — an array of
+ * step objects, each carrying `step_id` — and refuse everything else.
  *
- * format.md § Steps documents an array of steps, each carrying `step_id`, and
- * bans `id` outright. Accepting both is how a tree ends up with two names for
- * one thing: measured 2026-08-30, 101 steps in 77 files carried `step_id` and
- * six carried `id`, and every reader had to know about both. The V2 object
- * shape keys the same steps by their `step_id`, so normalising it writes that
- * key back onto the step — and nothing else.
+ * Two refusals, one rule each:
  *
- * Refusal is loud, not lenient: silently reading `id` is the fallback
- * `architecture-principles.md` §3 forbids, and it hides an authoring mistake
- * until something downstream reports `Step undefined`.
+ * 1. **Any shape but an array.** Owner decision 2026-09-05, fully authoritative
+ *    (`api/docs/governance/confirmations/cookbook-steps-shape.md` 001): `steps`
+ *    is an ARRAY, the only allowed shape, and the object variant "must not be
+ *    permitted or used anywhere". It supersedes the 2026-08-17 object
+ *    directive, which never landed in any runtime. The reason is order:
+ *    JavaScript reorders numeric object keys and Postgres `jsonb` does not
+ *    preserve key order either (measured M9,
+ *    `infra/api_monitoring/src/consumer/cookbookSplit.js:32-37`), so an
+ *    object-keyed cookbook has no defined execution order at all. Arrays keep
+ *    theirs, because a reordered step list IS a different cookbook.
  *
- * There is no `id` anywhere any more, at authoring time or at runtime. The
- * adapter that used to write `id = step_id` (`normalizeStepForExecutor`) went
- * with the executor it fed, and `@onlineapps/cookbook-executor` itself was
- * deleted on 2026-08-31 — WorkflowOrchestrator is the single owner of cookbook
- * execution and reads `step_id`. So this refusal is the whole rule, not one
- * half of it: `id` is banned by format.md § Steps, full stop.
+ *    Until 2026-09-05 this function converted the object into an array. That
+ *    was a FALSE GREEN and the reason the tolerance is gone: the offline Tier-1
+ *    gate accepted a cookbook the production WorkflowOrchestrator — which only
+ *    ever read arrays — threw on.
+ *
+ * 2. **A step spelling its identifier `id`.** The node bans it outright
+ *    (format.md § The array is the only accepted shape). Silently reading `id`
+ *    is the fallback
+ *    `architecture-principles.md` §3 forbids, and it hides an authoring mistake
+ *    until something downstream reports `Step undefined`. There is no `id`
+ *    anywhere any more: the adapter that wrote `id = step_id` went with
+ *    `@onlineapps/cookbook-executor` (deleted 2026-08-31), and
+ *    WorkflowOrchestrator — the single owner of cookbook execution — reads
+ *    `step_id`.
+ *
+ * An absent `steps` is NOT a shape problem: the caller owns that message,
+ * because only it knows whether it is reading a file or an object handed to it.
  *
  * @param {*} steps the raw value of the cookbook's top-level `steps`
- * @returns {object[]} the steps as an array; `[]` for anything else
- * @throws {Error} when any step carries `id`
+ * @returns {object[]} the steps, unchanged; `[]` when `steps` is absent
+ * @throws {Error} when `steps` is present but not an array, or a step carries `id`
  */
-function normalizeCookbookSteps(steps) {
-  if (!steps) {
+function readCookbookSteps(steps) {
+  if (steps === undefined || steps === null) {
     return [];
   }
 
-  let normalized;
-  if (Array.isArray(steps)) {
-    normalized = steps;
-  } else if (typeof steps === 'object') {
-    normalized = Object.entries(steps).map(([stepId, step]) => ({
-      ...step,
-      step_id: stepId
-    }));
-  } else {
-    return [];
+  if (!Array.isArray(steps)) {
+    throw new Error(
+      `[CookbookFormat] cookbook "steps" is ${describeStepsShape(steps)}, not an array - `
+      + 'Expected an ARRAY of step objects, each carrying its own "step_id" '
+      + `(${STEPS_DOC_REFERENCE}, cookbook format v${MIN_FORMAT_MAJOR_MINOR}; `
+      + 'owner confirmation cookbook-steps-shape 001 of 2026-09-05: the array is the only '
+      + 'allowed shape, because neither JS nor Postgres jsonb preserves object key order). '
+      + 'Fix: rewrite {"fetch": {...}, "send": {...}} as '
+      + '[{"step_id": "fetch", ...}, {"step_id": "send", ...}] — each key becomes that step\'s '
+      + '"step_id" and the array order becomes the execution order.'
+    );
   }
 
-  normalized.forEach((step, index) => {
+  steps.forEach((step, index) => {
     if (step && typeof step === 'object' && 'id' in step) {
       const label = stepIdentityOf(step) || `#${index + 1}`;
       throw new Error(
         `[CookbookFormat] step "${label}" carries "id" - Expected: "step_id" only `
-        + `(${DOC_REFERENCE.replace('§ Required fields', '§ Steps')}). Fix: rename "id" to "step_id"`
+        + `(${STEPS_DOC_REFERENCE}). Fix: rename "id" to "step_id"`
       );
     }
   });
 
-  return normalized;
+  return steps;
 }
 
 /**
  * The identifier a step declares. `step_id` is the ONLY spelling the format
- * allows; `normalizeCookbookSteps` refuses a step that carries `id`, so nothing
+ * allows; `readCookbookSteps` refuses a step that carries `id`, so nothing
  * downstream needs to know that name ever existed.
  *
  * @param {object} step one normalised step
@@ -166,7 +208,6 @@ function stepIdentityOf(step) {
 module.exports = {
   MIN_COOKBOOK_FORMAT_VERSION,
   checkCookbookFormatVersion,
-  compareVersions,
-  normalizeCookbookSteps,
+  readCookbookSteps,
   stepIdentityOf
 };