@onlineapps/conn-orch-validator 3.3.2 → 4.0.0

package/src/utils/integrationRun.js

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * Proof that the integration suite RAN — not that files exist on disk.
+ *
+ * The file-count check (`verifyIntegrationMinimum`) answers "is there a suite?".
+ * It cannot answer "did it execute?", and the difference is the whole defect:
+ * a suite hidden behind an env flag that CI never sets makes the pipeline start
+ * mariadb/redis/rabbitmq, pay for `ci:gate:wait` and `ci:gate:setup`, run nothing
+ * against them — and jest still exits 0. Measured: a fully skipped run reports
+ * `"success": true`, so the runner's exit code proves nothing either. The only
+ * usable evidence is the machine-readable report (`jest --json --outputFile`).
+ *
+ * This module is deliberately free of any dependency on bizCiGateContract: the
+ * CLI is the composition root that resolves the contract, the file list and the
+ * runner, and hands them in. Everything here is injected (principle 1) and
+ * validated at entry (principle 4).
+ *
+ * @see .claude/rules/automation-gates.md §5 — a mechanism that checks nothing
+ *      is a false guarantee, of the same severity as a wrong result.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Every counter the verdict rests on. A report missing one is not a report. */
+const REQUIRED_COUNTERS = {
+  totalTests: 'numTotalTests',
+  passedTests: 'numPassedTests',
+  failedTests: 'numFailedTests',
+  pendingTests: 'numPendingTests',
+  todoTests: 'numTodoTests',
+  totalSuites: 'numTotalTestSuites',
+  runtimeErrorSuites: 'numRuntimeErrorTestSuites',
+};
+
+const INTEGRATION_RUN_ARTEFACT_RELATIVE_PATH = path.join('ci', 'integration-run.json');
+const DEFAULT_REPORT_DIR_RELATIVE_PATH = path.join('ci', 'integration-run');
+
+function parseJestReport(rawText, sourcePath) {
+  if (typeof sourcePath !== 'string' || sourcePath === '') {
+    throw new Error('[BizCiGate] Missing sourcePath for runner report - Expected the path the report was read from. '
+      + 'Fix: pass the report path so a violation can name the failing process.');
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (error) {
+    throw new Error(`[BizCiGate] Unreadable runner report - ${sourcePath}: ${error.message}. `
+      + 'Expected the JSON document written by "jest --json --outputFile". '
+      + 'Fix: a truncated report means the runner was killed mid-write — rerun it and check the job for OOM.');
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`[BizCiGate] Invalid runner report - ${sourcePath} is not a jest report object. `
+      + 'Fix: point the gate at the file produced by "jest --json --outputFile".');
+  }
+
+  const report = { sourcePath };
+  for (const [field, counter] of Object.entries(REQUIRED_COUNTERS)) {
+    const value = parsed[counter];
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error(`[BizCiGate] Invalid runner report - ${sourcePath} has no usable "${counter}" `
+        + `(found ${JSON.stringify(value)}). Expected a non-negative integer. `
+        + 'Fix: the report must come from jest >= 29 run with --json; do not hand-edit it.');
+    }
+    report[field] = value;
+  }
+
+  return report;
+}
+
+function readJestReport(filePath) {
+  const resolvedPath = path.resolve(filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`[BizCiGate] Missing runner report - ${resolvedPath} was not written. `
+      + 'Expected "jest --json --outputFile" to produce it. '
+      + 'Fix: the runner died before writing — read the job log for the crash; a missing report is never a pass.');
+  }
+
+  return parseJestReport(fs.readFileSync(resolvedPath, 'utf8'), resolvedPath);
+}
+
+function aggregateJestReports(reports) {
+  if (!Array.isArray(reports) || reports.length === 0) {
+    throw new Error('[BizCiGate] No runner reports - Expected at least one jest report to aggregate. '
+      + 'Fix: an empty batch means no process ran; that is a failure, not a clean zero.');
+  }
+
+  const aggregate = { reportCount: reports.length, sourcePaths: [] };
+  for (const field of Object.keys(REQUIRED_COUNTERS)) {
+    aggregate[field] = 0;
+  }
+
+  for (const report of reports) {
+    aggregate.sourcePaths.push(report.sourcePath);
+    for (const field of Object.keys(REQUIRED_COUNTERS)) {
+      aggregate[field] += report[field];
+    }
+  }
+
+  // Executed = what the runner actually carried out. Pending (a skipped describe
+  // or it) and todo are declarations, not execution — counting them is exactly
+  // the lie this module exists to remove.
+  aggregate.executedTests = aggregate.passedTests + aggregate.failedTests;
+  aggregate.notExecutedTests = aggregate.pendingTests + aggregate.todoTests;
+
+  return aggregate;
+}
+
+/**
+ * Every violation is reported, not only the first: a job that skipped half its
+ * suite AND failed a test must show both, or the second one surfaces only after
+ * the first is fixed.
+ */
+function evaluateIntegrationRun(aggregate) {
+  if (!aggregate || typeof aggregate !== 'object') {
+    throw new Error('[BizCiGate] Missing aggregate - Expected the object returned by aggregateJestReports. '
+      + 'Fix: aggregate the reports before evaluating them.');
+  }
+
+  const violations = [];
+
+  if (aggregate.runtimeErrorSuites > 0) {
+    violations.push({
+      code: 'RUNTIME_ERROR_SUITES',
+      message: `[BizCiGate] Integration suite failed to load - ${aggregate.runtimeErrorSuites} suite(s) `
+        + 'threw before any test ran. Expected every suite to load against the real sidecars. '
+        + 'Fix: read the runner output above; a suite that cannot load fails 0 tests and proves nothing.',
+    });
+  }
+
+  if (aggregate.failedTests > 0) {
+    violations.push({
+      code: 'FAILED_TESTS',
+      message: `[BizCiGate] Failing integration test(s) - ${aggregate.failedTests} of `
+        + `${aggregate.executedTests} executed test(s) failed. Expected all to pass. `
+        + 'Fix: fix the service or the test; never loosen the assertion.',
+    });
+  }
+
+  if (aggregate.executedTests === 0) {
+    violations.push({
+      code: 'NO_TESTS_EXECUTED',
+      message: `[BizCiGate] No integration test was executed - ${aggregate.totalTests} test(s) discovered, `
+        + `0 executed, ${aggregate.notExecutedTests} skipped. `
+        + 'The pipeline started the sidecars and ran nothing against them. '
+        + 'Fix: remove the condition that disables the suite, or delete the suite.',
+    });
+  } else if (aggregate.notExecutedTests > 0) {
+    violations.push({
+      code: 'NOT_EXECUTED_TESTS',
+      message: `[BizCiGate] Skipped integration test(s) - ${aggregate.pendingTests} skipped, `
+        + `${aggregate.todoTests} todo, out of ${aggregate.totalTests}. `
+        + 'Expected: every integration test runs against the real sidecars. '
+        + 'Fix: remove the skip/todo, or delete the test.',
+    });
+  }
+
+  return {
+    ok: violations.length === 0,
+    violations,
+    executedTests: aggregate.executedTests,
+    notExecutedTests: aggregate.notExecutedTests,
+    totalTests: aggregate.totalTests,
+  };
+}
+
+function assertNonEmptyString(value, name, fix) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`[BizCiGate] Missing ${name} - Expected a non-empty path. Fix: ${fix}`);
+  }
+}
+
+function assertExistingPath(value, name, fix) {
+  if (!fs.existsSync(value)) {
+    throw new Error(`[BizCiGate] Missing ${name} - ${value} does not exist. Fix: ${fix}`);
+  }
+}
+
+/**
+ * One runner process per integration test file.
+ *
+ * The service declares WHAT its integration suite is; the library decides HOW it
+ * is executed (docs/biz/00-model/uniformity-principle.md). Per-file processes are
+ * the uniform HOW because they are the only shape that also fits biz-invoicing,
+ * whose suite was OOM-killed in a single process — and they bound the blast radius
+ * of one leaking suite for everybody else. No new declaration is needed for it.
+ */
+function runIntegrationSuite(options) {
+  const { serviceRoot, testFiles, jestBin, jestConfig, reportDir, spawn } = options || {};
+
+  assertNonEmptyString(serviceRoot, 'serviceRoot', 'pass the resolved service repository root.');
+  assertNonEmptyString(jestBin, 'jestBin', 'pass the resolved path to the runner executable.');
+  assertNonEmptyString(jestConfig, 'jestConfig', 'pass the resolved path to the runner config.');
+  assertNonEmptyString(reportDir, 'reportDir', 'pass the directory the per-process reports are written to.');
+
+  if (typeof spawn !== 'function') {
+    throw new Error('[BizCiGate] Missing spawn - Expected the process runner to be injected. '
+      + 'Fix: pass child_process.spawnSync (or an equivalent) from the composition root.');
+  }
+
+  if (!Array.isArray(testFiles) || testFiles.length === 0) {
+    throw new Error('[BizCiGate] No integration test files - Expected at least one file to run. '
+      + 'Fix: this is the file-count precondition; run verify-integration-minimum first.');
+  }
+
+  assertExistingPath(jestBin, 'runner executable',
+    'install the service dependencies (npm ci) so node_modules/.bin/jest exists.');
+  assertExistingPath(jestConfig, 'runner config',
+    'the service must ship jest.config.js at its repository root.');
+
+  fs.rmSync(reportDir, { recursive: true, force: true });
+  fs.mkdirSync(reportDir, { recursive: true });
+
+  const processes = [];
+  for (const [index, testFile] of testFiles.entries()) {
+    const relativeTestFile = path.relative(serviceRoot, path.resolve(serviceRoot, testFile));
+    const reportPath = path.join(reportDir, `${index}-${path.basename(testFile)}.json`);
+    const args = [
+      '--config', jestConfig,
+      relativeTestFile,
+      '--runInBand',
+      '--json',
+      '--outputFile', reportPath,
+    ];
+
+    const spawnResult = spawn(jestBin, args, { cwd: serviceRoot, stdio: 'inherit', env: process.env });
+
+    processes.push({
+      testFile: relativeTestFile,
+      reportPath,
+      exitCode: spawnResult && Number.isInteger(spawnResult.status) ? spawnResult.status : null,
+    });
+  }
+
+  // Read every report before judging any of them: a missing or truncated report
+  // throws here, which is the intended outcome — it can never be read as "0 failures".
+  const reports = processes.map((entry) => readJestReport(entry.reportPath));
+  const aggregate = aggregateJestReports(reports);
+  const evaluation = evaluateIntegrationRun(aggregate);
+
+  const artefact = {
+    generatedAt: new Date().toISOString(),
+    serviceRoot,
+    processes,
+    executedTests: aggregate.executedTests,
+    notExecutedTests: aggregate.notExecutedTests,
+    totalTests: aggregate.totalTests,
+    passedTests: aggregate.passedTests,
+    failedTests: aggregate.failedTests,
+    pendingTests: aggregate.pendingTests,
+    todoTests: aggregate.todoTests,
+    totalSuites: aggregate.totalSuites,
+    runtimeErrorSuites: aggregate.runtimeErrorSuites,
+    verdict: evaluation.ok ? 'pass' : 'fail',
+    violations: evaluation.violations,
+  };
+
+  const artefactPath = path.join(serviceRoot, INTEGRATION_RUN_ARTEFACT_RELATIVE_PATH);
+  fs.mkdirSync(path.dirname(artefactPath), { recursive: true });
+  fs.writeFileSync(artefactPath, JSON.stringify(artefact, null, 2));
+
+  return { aggregate, evaluation, processes, artefact, artefactPath };
+}
+
+/**
+ * The run artefact is the only honest source of "how many integration tests
+ * executed". Absent means unknown — the caller must say so, never substitute a
+ * count of files on disk.
+ */
+function readIntegrationRunArtefact(serviceRoot) {
+  const artefactPath = path.join(path.resolve(serviceRoot), INTEGRATION_RUN_ARTEFACT_RELATIVE_PATH);
+  if (!fs.existsSync(artefactPath)) {
+    return null;
+  }
+
+  try {
+    return { artefactPath, artefact: JSON.parse(fs.readFileSync(artefactPath, 'utf8')) };
+  } catch (error) {
+    throw new Error(`[BizCiGate] Unreadable integration run artefact - ${artefactPath}: ${error.message}. `
+      + 'Fix: delete it and rerun run-integration; a corrupt artefact must not be summarised as a result.');
+  }
+}
+
+module.exports = {
+  REQUIRED_COUNTERS,
+  INTEGRATION_RUN_ARTEFACT_RELATIVE_PATH,
+  DEFAULT_REPORT_DIR_RELATIVE_PATH,
+  parseJestReport,
+  readJestReport,
+  aggregateJestReports,
+  evaluateIntegrationRun,
+  runIntegrationSuite,
+  readIntegrationRunArtefact,
+};

package/src/utils/libCompat.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * Library compatibility gate — requirement R6.
+ *
+ * A biz service may only ship if every @onlineapps/* package it pins EXACTLY
+ * matches the version the platform declares. Mismatch means the service was
+ * built against a different platform contract than the one it will run on.
+ *
+ * Only packages at least one infra service actually installs are compared: the
+ * SSOT lists biz-only packages too, and for those there is no infra version to
+ * diverge from, so asking "does this match what infra ships" has no answer.
+ * The SSOT carries that set as `infraConsumed`. A bare version map has no such
+ * list — a platform-release entry records what was deployed, so everything in
+ * it is by definition shipped and must match.
+ *
+ * Pure module: the rules and the fetch live here, presentation and exit codes
+ * live in the CLI.
+ *
+ * Configuration (GitLab CI variables, NOT service env files — the biz env
+ * convention in api/docs/biz/60-templates/env-conventions.md governs
+ * config/env-active/*.env and compose, and deliberately does not reach CI job
+ * variables, so these carry no DEVEL_/TESTING_ prefix):
+ *   LIBRARIES_SSOT_URL    where the platform SSOT is published
+ *   LIBRARIES_SSOT_TOKEN  optional read token for that endpoint
+ *
+ * Both are PLATFORM-GLOBAL: one value, set once at GitLab group level, shared
+ * by all biz repos and every developer. They have no tenant or workspace
+ * dimension, and must not grow one. `workspace_id` scopes tenant DATA at
+ * runtime; this pair answers "which platform contract was this code built
+ * against", which is a property of the build, identical for every tenant. A
+ * per-workspace SSOT would mean two workspaces could run the same service
+ * built against different library sets — the exact divergence R6 exists to
+ * prevent. Compare TESTING_TENANT_ID / TESTING_WORKSPACE_ID, which are
+ * per-service test fixtures and therefore legitimately differ.
+ */
+
+const fs = require('fs');
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+const SCOPE = '@onlineapps/';
+
+/**
+ * Resolve the SSOT into a version map plus its optional infraConsumed list.
+ * Accepts the committed wrapped shape and a bare map alike.
+ */
+function normalizeLibrarySet(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('[LibCompat] Invalid library set - Expected a JSON object. '
+      + 'Fix: point LIBRARIES_SSOT_URL at config/libraries.json or a platform-release libraries entry.');
+  }
+  if (raw.libraries && typeof raw.libraries === 'object') {
+    return {
+      versions: raw.libraries,
+      infraConsumed: Array.isArray(raw.infraConsumed) ? new Set(raw.infraConsumed) : null
+    };
+  }
+  return { versions: raw, infraConsumed: null };
+}
+
+/**
+ * Compare a package.json against the platform library set.
+ *
+ * @param {object} pkg parsed package.json of the biz service
+ * @param {object} librarySet committed SSOT shape or bare version map
+ * @returns {{ok: boolean, gated: string[], notGated: string[], violations: Array<{package: string, message: string}>}}
+ */
+function checkLibCompat(pkg, librarySet) {
+  const { versions, infraConsumed } = normalizeLibrarySet(librarySet);
+
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const ours = Object.entries(deps).filter(([name]) => name.startsWith(SCOPE));
+
+  const gated = infraConsumed ? ours.filter(([name]) => infraConsumed.has(name)) : ours;
+  const notGated = infraConsumed
+    ? ours.filter(([name]) => !infraConsumed.has(name)).map(([name]) => name)
+    : [];
+
+  const violations = [];
+  for (const [name, version] of gated) {
+    if (!EXACT_VERSION.test(version)) {
+      violations.push({
+        package: name,
+        message: `${name}: version '${version}' is not exact x.y.z — caret/tilde/range pins are banned, `
+          + 'because what resolves today is not what resolved when the image was built.'
+      });
+      continue;
+    }
+    if (!(name in versions)) {
+      violations.push({
+        package: name,
+        message: `${name}: not present in the infra library set — the platform does not ship this package version contract.`
+      });
+      continue;
+    }
+    if (versions[name] !== version) {
+      violations.push({
+        package: name,
+        message: `${name}: biz pins ${version}, infra ships ${versions[name]} — `
+          + 'rebuild the service against the current platform, or deploy the matching infra release first.'
+      });
+    }
+  }
+
+  return {
+    ok: violations.length === 0,
+    gated: gated.map(([name]) => name),
+    notGated,
+    violations
+  };
+}
+
+/**
+ * Load the SSOT from a local path or an https endpoint.
+ *
+ * Fail-fast when unconfigured: a gate that silently passes because it could not
+ * find its reference is worse than no gate, since it reports success.
+ *
+ * @param {string} [source] path or URL; defaults to LIBRARIES_SSOT_URL
+ * @param {object} [env] environment to read (injected for testability)
+ */
+async function loadLibrarySet(source, env = process.env) {
+  const location = source || env.LIBRARIES_SSOT_URL;
+
+  if (!location) {
+    throw new Error('[LibCompat] Missing environment variable - LIBRARIES_SSOT_URL is required '
+      + '(or pass --libraries <path|url>). It points at the platform library SSOT the biz pins are compared against. '
+      + 'Fix: set LIBRARIES_SSOT_URL as a GitLab CI variable at group level.');
+  }
+
+  if (/^https?:\/\//.test(location)) {
+    const headers = { Accept: 'application/json' };
+    if (env.LIBRARIES_SSOT_TOKEN) headers['PRIVATE-TOKEN'] = env.LIBRARIES_SSOT_TOKEN;
+
+    const response = await fetch(location, { headers });
+    if (!response.ok) {
+      throw new Error(`[LibCompat] Could not fetch the library SSOT - ${location} returned ${response.status} ${response.statusText}. `
+        + 'Fix: check LIBRARIES_SSOT_URL, and that LIBRARIES_SSOT_TOKEN grants read access to the infra repository.');
+    }
+    const body = await response.text();
+    try {
+      return JSON.parse(body);
+    } catch (err) {
+      throw new Error(`[LibCompat] Could not parse the library SSOT fetched from ${location} - ${err.message}`);
+    }
+  }
+
+  if (!fs.existsSync(location)) {
+    throw new Error(`[LibCompat] Library SSOT not found: ${location}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(location, 'utf8'));
+  } catch (err) {
+    throw new Error(`[LibCompat] Could not parse ${location} - ${err.message}`);
+  }
+}
+
+module.exports = { checkLibCompat, loadLibrarySet, normalizeLibrarySet };

package/src/utils/preValidation.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * Pre-validation: run a service's cookbooks offline against mocked
+ * infrastructure and write the validation proof the Registry consumes.
+ *
+ * One implementation for every service. It replaces five copies of
+ * scripts/run-pre-validation.js — four identical, plus property's 16-line
+ * stand-in that counted .json files and printed OK without running a cookbook
+ * or writing a proof, while being wired to the same `npm run test:cookbooks`.
+ *
+ * Two things the copies carried are deliberately absent:
+ *   - the legacy HTTP branch (spawn scripts/test-server.js, dispatch over
+ *     axios). Every service declares schema_version "3.0" with handler
+ *     operations, so the branch was unreachable; a non-v3 shape now fails fast
+ *     rather than silently taking the handler path.
+ *   - a ConfigLoader import. That lives in @onlineapps/service-wrapper (L4) and
+ *     this package is L3, so the resolved service URL is INJECTED by the
+ *     caller — architecture-principles.md §7, no reverse dependencies.
+ *
+ * Pure module: it returns the outcome and never exits. The CLI owns exit codes
+ * and presentation, this owns the rules.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * A step error is whatever the handler threw or the transport returned — often
+ * an object, not a string. The scripts this replaces interpolated it straight
+ * into a template literal, so a real failure was reported as "[object Object]"
+ * and the operator learned nothing. Render it so the message survives.
+ */
+function describeStepError(error) {
+  if (error === undefined || error === null) return 'Validation failed';
+  if (typeof error === 'string') return error;
+  if (typeof error.message === 'string' && error.message.length > 0) return error.message;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+const COOKBOOKS_RELATIVE_DIR = path.join('tests', 'cookbooks');
+const PROOF_RELATIVE_PATH = path.join('conn-runtime', 'validation-proof.json');
+const OPERATIONS_RELATIVE_PATH = path.join('config', 'service', 'operations.json');
+const VALIDATOR_NAME = '@onlineapps/conn-orch-validator';
+const COOKBOOK_TIMEOUT_MS = 30000;
+
+/**
+ * v3 means MQ-only handler dispatch. Anything else is a service that has not
+ * been migrated, and it must say so rather than be run through a path its
+ * operations were never written for.
+ */
+function assertV3Operations(serviceRoot) {
+  const operationsPath = path.join(serviceRoot, OPERATIONS_RELATIVE_PATH);
+
+  if (!fs.existsSync(operationsPath)) {
+    throw new Error(`[PreValidation] Missing operations.json - ${operationsPath} is required. `
+      + 'Fix: declare the service operations at config/service/operations.json.');
+  }
+
+  const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf8'));
+  const declaresV3 = operations.schema_version === '3.0' || operations.schema_version === '3';
+  const hasHandlers = operations.operations
+    && Object.values(operations.operations).some((operation) => operation.handler);
+
+  if (!declaresV3 && !hasHandlers) {
+    throw new Error('[PreValidation] Unsupported operations.json shape - schema_version "3.0" with '
+      + 'handler-based operations is required. Fix: migrate the service to v3 handlers; the legacy '
+      + 'HTTP dispatch path no longer exists.');
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.serviceRoot service repository root
+ * @param {string} params.serviceUrl resolved by the caller from the service's own config
+ * @param {Function} params.RunnerClass CookbookTestRunner (injected so the module stays testable)
+ * @param {Function} params.ProofGeneratorClass ValidationProofGenerator
+ * @param {{log: Function, error: Function}} params.logger
+ * @returns {Promise<{ok: boolean, results: object, failedSteps: Array, proof: object|null, proofPath: string|null}>}
+ */
+async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGeneratorClass, logger }) {
+  const cookbooksDir = path.join(serviceRoot, COOKBOOKS_RELATIVE_DIR);
+  if (!fs.existsSync(cookbooksDir)) {
+    throw new Error(`[PreValidation] Missing cookbooks directory - ${cookbooksDir} is required. `
+      + 'Fix: add cookbook .json files under tests/cookbooks.');
+  }
+
+  assertV3Operations(serviceRoot);
+
+  const packageJson = JSON.parse(fs.readFileSync(path.join(serviceRoot, 'package.json'), 'utf8'));
+
+  const runner = new RunnerClass({
+    serviceName: packageJson.name,
+    serviceUrl,
+    servicePath: serviceRoot,
+    mockInfrastructure: true,
+    timeout: COOKBOOK_TIMEOUT_MS,
+    logger
+  });
+
+  const results = await runner.runCookbooks(cookbooksDir);
+
+  if (results.failed > 0) {
+    // No proof on a failed run. A proof is a claim that the cookbooks passed,
+    // so writing one here would make the Registry trust a run that did not.
+    const failedSteps = results.steps
+      .filter((step) => !step.passed)
+      .map((step) => ({
+        id: step.id || step.operation,
+        error: describeStepError(step.error),
+        validationErrors: step.validationErrors || []
+      }));
+
+    return { ok: false, results, failedSteps, proof: null, proofPath: null };
+  }
+
+  const proofGenerator = new ProofGeneratorClass({
+    serviceName: packageJson.name,
+    serviceVersion: packageJson.version,
+    validatorName: VALIDATOR_NAME,
+    validatorVersion: require('../../package.json').version
+  });
+
+  const proof = proofGenerator.generateProof(results, packageJson.dependencies || {});
+
+  const proofPath = path.join(serviceRoot, PROOF_RELATIVE_PATH);
+  fs.mkdirSync(path.dirname(proofPath), { recursive: true });
+  fs.writeFileSync(proofPath, JSON.stringify(proof, null, 2));
+
+  return { ok: true, results, failedSteps: [], proof, proofPath };
+}
+
+module.exports = { runPreValidation, PROOF_RELATIVE_PATH, COOKBOOKS_RELATIVE_DIR };