@onlineapps/conn-orch-validator 3.3.2 → 4.0.1

package/src/utils/setupDatabase.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * The one schema build for every biz service.
+ *
+ * The service declares WHAT its database is in integration-contract.json; this
+ * decides HOW it gets built, identically for all of them
+ * (docs/biz/00-model/uniformity-principle.md).
+ *
+ * It replaces six per-repo ci-setup-db.js scripts that had each solved the same
+ * problem differently — 113, 69, 56, 54, 22 and 20 lines, in three strategies,
+ * two of which bypassed migrations entirely with sequelize.sync(). That bypass
+ * let a service's CI prove a schema built from models while production ran one
+ * built from hand-applied migrations. There is deliberately no option here to
+ * build from anything but the migrations: the absence is what makes the bypass
+ * impossible rather than merely discouraged.
+ *
+ * Two invariants, both from ADR 0006:
+ *
+ *   §2 every .sql file in the declared directory is applied, in sorted order.
+ *      No list lives in this file — the set grows with each schema change, and a
+ *      list would drift until a missing table surfaced in an unrelated test.
+ *
+ *   §3 foreign key checks stay ON. Deferring them would let a migration
+ *      reference a table a later file creates and still report success, which is
+ *      the exact defect class building from empty exists to catch.
+ *
+ * SQL runs through the mysql/mariadb CLI rather than a driver, because trigger
+ * definitions use DELIMITER — a client directive drivers report as a syntax
+ * error. The executor is injected so the decisions are testable without a
+ * database.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function requireValue(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`[SetupDatabase] Missing ${name} - Expected a value. `
+      + `Fix: set ${name} in the CI job (or env-active/*.env locally).`);
+  }
+  return value;
+}
+
+/**
+ * Decide which files to apply and in what order.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {{migrations: string, seeds: string[]}} database the contract declaration
+ */
+function resolveMigrationPlan(serviceRoot, database) {
+  // The declaration is a glob-ish path; only the directory part is read, and
+  // only its own .sql files — subdirectories such as migrations/superseded/ hold
+  // the record of how a baseline was reached and must not be replayed.
+  const dir = path.resolve(serviceRoot, path.dirname(database.migrations));
+
+  if (!fs.existsSync(dir)) {
+    throw new Error(`[SetupDatabase] Migrations directory not found: ${dir}\n`
+      + `       Fix: create it, or correct database.migrations in the integration contract.`);
+  }
+
+  const migrations = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => path.join(dir, name));
+
+  if (migrations.length === 0) {
+    throw new Error(`[SetupDatabase] No .sql files in ${dir} - refusing to report a schema as built.\n`
+      + '       Fix: the migration set is the source of truth for the schema; it cannot be empty.');
+  }
+
+  const seeds = (database.seeds ?? []).map((seed) => {
+    const file = path.resolve(serviceRoot, seed);
+    if (!fs.existsSync(file)) {
+      throw new Error(`[SetupDatabase] Declared seed not found: ${seed}\n`
+        + '       Fix: correct database.seeds in the integration contract, or add the file.');
+    }
+    return file;
+  });
+
+  return { dir, migrations, seeds };
+}
+
+/** Run one statement or file through the CLI client. Injectable for tests. */
+function defaultExec({ connection, schema, sql, file }) {
+  const client = ['mariadb', 'mysql'].find((bin) => !spawnSync(bin, ['--version'], { encoding: 'utf8' }).error);
+  if (!client) {
+    return {
+      status: 1,
+      stderr: '[SetupDatabase] No mysql/mariadb client on PATH - required because migrations use DELIMITER. '
+        + 'Fix: install mariadb-client in the CI job image.'
+    };
+  }
+
+  const args = ['-h', connection.host, '-P', String(connection.port), '-u', connection.user,
+    '--default-character-set=utf8mb4'];
+  // MariaDB Connector/C 3.x requires TLS by default and the CI database is a
+  // sidecar with none; the connection never leaves the job's private network.
+  if (connection.requireTls !== true) args.push('--skip-ssl');
+  if (connection.password) args.push(`-p${connection.password}`);
+  if (schema) args.push(schema);
+
+  const result = spawnSync(client, args, {
+    input: sql !== undefined ? sql : fs.readFileSync(file, 'utf8'),
+    encoding: 'utf8'
+  });
+
+  return {
+    status: result.error ? 1 : result.status,
+    stderr: result.error ? result.error.message
+      : (result.stderr || '').split('\n').filter((l) => !l.includes('Using a password')).join('\n').trim()
+  };
+}
+
+/**
+ * Build the schema from the declared migrations.
+ *
+ * @returns {{schema: string, migrationsApplied: number, seedsApplied: number}}
+ */
+function buildSchema({ serviceRoot, database, connection, exec = defaultExec }) {
+  requireValue(connection?.host, 'DB_HOST');
+  requireValue(connection?.user, 'DB_USER');
+  const port = connection.port ?? 3306;
+
+  const conn = { ...connection, port };
+  const plan = resolveMigrationPlan(serviceRoot, database);
+
+  const created = exec({ connection: conn, sql: `CREATE DATABASE IF NOT EXISTS \`${database.schema}\`;` });
+  if (created.status !== 0) {
+    throw new Error(`[SetupDatabase] Could not create schema ${database.schema}:\n${created.stderr}`);
+  }
+
+  const apply = (file, kind) => {
+    const result = exec({ connection: conn, schema: database.schema, file });
+    if (result.status !== 0) {
+      throw new Error(`[SetupDatabase] ${kind} ${path.basename(file)} failed:\n${result.stderr}\n`
+        + '       Fix: the set must apply to an empty database in file order. Either the SQL is wrong, '
+        + 'or the file is numbered before something it depends on.');
+    }
+  };
+
+  for (const file of plan.migrations) apply(file, 'Migration');
+  for (const file of plan.seeds) apply(file, 'Seed');
+
+  return {
+    schema: database.schema,
+    migrationsApplied: plan.migrations.length,
+    seedsApplied: plan.seeds.length
+  };
+}
+
+module.exports = { resolveMigrationPlan, buildSchema };

package/src/utils/stepFailure.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * One owner for the sentence that says WHY a cookbook step failed.
+ *
+ * Two consumers read it and they must not drift apart:
+ *   - CookbookTestRunner.executeStep — the per-step log line at boot;
+ *   - ValidationOrchestrator.runCookbookTests — the step-4 error list that
+ *     reaches `results.errors`, the wrapper's `Validation failed: …` message
+ *     and validation.responses.
+ *
+ * Before 2026-08-29 neither of them said anything: the log line was
+ * `Step count_stub: FAILED (1101ms)` and the orchestrator's only error was
+ * `1 cookbook test(s) failed`. The reason existed the whole time in
+ * `result.validationErrors` / `result.error` and was discarded at both ends,
+ * so a failed biz-hello boot could not be diagnosed from its own logs
+ * (automation-gates.md §5 — silence is a defect).
+ */
+
+/**
+ * Why this step failed, in one line, from whichever field holds it.
+ *
+ * @param {Object} stepResult - a step result produced by CookbookTestRunner
+ * @returns {string} the concrete reason; never an empty string
+ */
+function describeStepFailure(stepResult) {
+  if (!stepResult || typeof stepResult !== 'object') {
+    throw new Error('[stepFailure] stepResult is required - Expected the step result object produced by CookbookTestRunner');
+  }
+
+  const parts = [];
+
+  if (Array.isArray(stepResult.validationErrors) && stepResult.validationErrors.length > 0) {
+    parts.push(stepResult.validationErrors.join('; '));
+  }
+
+  const error = stepResult.error;
+  if (typeof error === 'string' && error.length > 0) {
+    parts.push(error);
+  } else if (error && typeof error === 'object') {
+    parts.push(`${error.code || 'HANDLER_ERROR'}: ${error.message}`);
+  }
+
+  if (typeof stepResult.errorStack === 'string' && stepResult.errorStack.length > 0) {
+    parts.push(stepResult.errorStack);
+  }
+
+  if (parts.length === 0) {
+    // A step marked failed with nothing recorded is itself a defect; say so
+    // rather than printing an empty reason that reads like "no problem".
+    return 'no reason recorded — neither validationErrors nor error was set on the step result';
+  }
+
+  return parts.join(' | ');
+}
+
+/**
+ * The same reason, prefixed with enough context to find the case: which
+ * cookbook, which step, which operation. This is what step 4 puts into
+ * `results.errors`.
+ *
+ * @param {Object} stepResult - a step result carrying `cookbook`
+ * @returns {string}
+ */
+function describeStepFailureWithContext(stepResult) {
+  const reason = describeStepFailure(stepResult);
+  const cookbook = stepResult.cookbook || 'unknown cookbook';
+  const stepId = stepResult.id || stepResult.step_id || 'unnamed step';
+  const operation = stepResult.operation ? ` (${stepResult.operation})` : '';
+  return `cookbook "${cookbook}" step "${stepId}"${operation}: ${reason}`;
+}
+
+module.exports = { describeStepFailure, describeStepFailureWithContext };

package/src/utils/testNamespace.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * The tenant / workspace an integration test is allowed to write into.
+ *
+ * An integration test reaches a real database, so the namespace it targets is a
+ * safety boundary. Two incidents show what happens when that boundary is
+ * written per file instead of read from one source:
+ *
+ *   biz-property and biz-converter overrode TESTING_TENANT_ID in their own env
+ *   template to point at the LIVE tenant, because that is where their cookbook
+ *   fixtures happened to exist. The Tier-1 runner executes real handler
+ *   dispatch at every service start, production included — so every restart
+ *   wrote into real data, and did.
+ *
+ *   24 of biz-property's 26 integration tests carried their own
+ *   `const TENANT = 100` and inserted and deleted under it. Nothing could
+ *   redirect them, because there was nothing to redirect.
+ *
+ * So the value comes from the platform env (`TESTING_TENANT_ID` /
+ * `TESTING_WORKSPACE_ID`, set in `config/env-templates/shared.env`) and this
+ * module is the only place that reads it. It throws when the env is absent
+ * rather than guessing: a test that does not know which namespace it owns must
+ * not write anywhere at all.
+ *
+ * Enforced by deploy-contract requirement R8 (see utils/deployContract.js).
+ */
+
+/**
+ * The environment classes a validation or test run may write into.
+ *
+ * This is a WHITELIST, and that is the whole point. The previous rule refused
+ * the one tenant an env var declared live (`PLATFORM_LIVE_TENANT_ID=100`), which
+ * left every customer tenant — 101+, production, real data, 101 = Meditest —
+ * outside the guard, and the gap grew with every customer onboarded. Naming what
+ * is permitted cannot grow a gap: a class that is not on this list is refused
+ * whether or not anyone remembered to declare it.
+ *
+ * Why the values live in the library and not in the environment: they are a
+ * CONTRACT CONSTANT taken from a normative standard, not a deployment knob. The
+ * standard says WHAT each tenant id means (an environment class, allocated once,
+ * "Adding a class — do not"); this module is the HOW of enforcing it at run time.
+ * Architecture principle §2 (No Hardcoded Values) targets configuration of an
+ * environment — ports, hosts, timeouts, credentials — which differs per
+ * deployment by design. This boundary does not: it is identical in every
+ * environment because the norm defines it, and making it env-settable would hand
+ * the very misconfiguration this guard exists to stop a switch to turn it off.
+ *
+ * @see api/docs/standards/tenant-allocation.md § "The allocation"
+ */
+const ALLOWED_TENANT_CLASSES = Object.freeze([
+  96, // CI
+  97, // TESTING
+  98, // DEVEL
+  99 //  VALIDATION
+]);
+
+function readNamespaceId(key) {
+  const raw = process.env[key];
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    throw new Error(`[TestNamespace] Missing environment variable - ${key} is required. `
+      + 'Fix: set it in config/env-active/shared.env (the platform default is the '
+      + 'non-production namespace). An integration test may not pick a namespace itself.');
+  }
+  const value = Number(String(raw).trim());
+  if (!Number.isInteger(value)) {
+    throw new Error(`[TestNamespace] Invalid ${key}="${raw}" - Expected an integer id. `
+      + 'Fix: correct the value in config/env-active/shared.env.');
+  }
+  return value;
+}
+
+/**
+ * @returns {{tenant_id: number, workspace_id: number}} ctx-shaped, so it can be
+ *          spread straight into a handler call.
+ */
+function getTestNamespace() {
+  const tenantId = readNamespaceId('TESTING_TENANT_ID');
+
+  // The runtime half of the protection, and the reason the tenant is decided
+  // before anything else is read. R8 rejects a per-service override before it
+  // ships; this refuses the accident that ships anyway, so a startup probe can
+  // never reach real data even if the configuration is wrong.
+  //
+  // The workspace id is deliberately NOT class-checked: tenant-allocation.md
+  // allocates environment classes to TENANTS, and calls a workspace "the purpose
+  // within the class" without naming any range for it. A restriction here would
+  // be one this library invented.
+  if (!ALLOWED_TENANT_CLASSES.includes(tenantId)) {
+    throw new Error(`[TestNamespace] TESTING_TENANT_ID=${tenantId} is not an allowed `
+      + 'environment class - test and validation runs may never write into production data '
+      + '(100 = LIVE, 101+ = CUSTOMER tenants, both refused). Expected one of 96 (CI), '
+      + '97 (TESTING), 98 (DEVEL), 99 (VALIDATION). Fix: set TESTING_TENANT_ID to one of '
+      + 'those classes in config/env-active/shared.env and seed that namespace from '
+      + 'migrations/ - see api/docs/standards/tenant-allocation.md.');
+  }
+
+  return {
+    tenant_id: tenantId,
+    workspace_id: readNamespaceId('TESTING_WORKSPACE_ID')
+  };
+}
+
+module.exports = { getTestNamespace };

package/src/validators/ServiceStructureValidator.js

@@ -37,6 +37,184 @@ function hasConfigDir(root) {
          fs.existsSync(path.join(root, 'conn-config'));
 }
 
+
+// ---------------------------------------------------------------------------
+// v1.2 — business-error CONTRACT (DÁVKA 50)
+//
+// Owner decision: api/docs/governance/confirmations/business-error-contract.md
+// (20260829-1500-business-error-contract-001, CONFIRMED).
+//
+// v1.2 used to ask "does the service depend on @onlineapps/service-common and
+// import an error class FROM IT?". Both retired checks (`dep_service_common`,
+// `business_error_usage`) demanded the defeated hierarchy, so a service that had
+// already migrated to the wrapper's classes failed the gate for being correct.
+//
+// The question is now the contract, which survives the package moving: does the
+// service raise errors that the wrapper's ErrorMapper will translate — i.e. a
+// BusinessError family from @onlineapps/service-wrapper, or its own class
+// declaring the brand `onlineapps.businessError`?
+//
+// Scope is ANY file under src/, not "a handler or a src/lib/ module a handler
+// requires" — one rule, one sentence (automation-gates.md §1 requirement 2,
+// Simple). A static check cannot prove a `throw` reaches a handler anyway; it
+// can only see the declaration. The narrower rule was measured on 2026-08-29
+// and failed biz-converter and biz-ingest, both of which declare the contract in
+// src/lib/ and reach it through src/services/. Lead decision, same day.
+// ---------------------------------------------------------------------------
+
+/** Names exported by the wrapper's error module that satisfy the contract. */
+const WRAPPER_ERROR_NAMES = [
+  'BusinessError',
+  'ValidationError',
+  'NotFoundError',
+  'ConflictError',
+  'BusinessRuleError',
+  'AuthorizationError',
+  'InvalidEnvelopeError',
+  'BUSINESS_ERROR_BRAND'
+];
+
+/**
+ * The RETIRED hierarchy: everything @onlineapps/service-common exports from
+ * src/errors/BusinessError.js. Deliberately NOT every error class in that
+ * package — `ScopedRegistryError` belongs to the live scoped-registry helper and
+ * is not part of what DÁVKA 50 retires.
+ */
+const RETIRED_ERROR_NAMES = [
+  'BusinessError',
+  'NotFoundError',
+  'ValidationError',
+  'ConflictError',
+  'BusinessRuleError',
+  'AuthorizationError',
+  'ServiceUnavailableError',
+  'isBusinessError',
+  'ERROR_TYPES',
+  'businessErrorHandler'
+];
+
+const BUSINESS_ERROR_BRAND_TOKEN = 'onlineapps.businessError';
+
+function requirePattern(pkg) {
+  return new RegExp(`require\\(\\s*['"]${pkg.replace('/', '\\/')}['"]\\s*\\)`);
+}
+
+/** Collect every .js file under `dir`, as paths relative to `root`. */
+function listJsFiles(root, dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.isFile() && entry.name.endsWith('.js')) out.push(path.relative(root, p));
+    }
+  };
+  try { walk(dir); } catch { /* unreadable tree — callers treat as empty */ }
+  return out;
+}
+
+function readFile(root, rel) {
+  try { return fs.readFileSync(path.join(root, rel), 'utf-8'); } catch { return null; }
+}
+
+/**
+ * Names destructured from `require('<pkg>')` in `content`, across every such
+ * statement (single-line or multi-line).
+ *
+ * The body is `[^{}]*?`, NOT `[\s\S]*?`: a lazy any-character body starts at the
+ * nearest preceding `const {` and swallows whole lines to reach the right
+ * `require`, which dropped the first imported name. Measured on
+ * `api_biz/meta/src/handlers/persons.js:10-11`, where an unrelated `models`
+ * destructuring sits directly above the service-common one.
+ *
+ * @returns {string[]}
+ */
+function destructuredFrom(content, pkg) {
+  const re = new RegExp(
+    `(?:const|let|var)\\s*\\{([^{}]*?)\\}\\s*=\\s*require\\(\\s*['"]${pkg.replace('/', '\\/')}['"]\\s*\\)`,
+    'g'
+  );
+  const names = [];
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    for (const raw of m[1].split(',')) {
+      const name = raw.split(':')[0].trim();
+      if (name) names.push(name);
+    }
+  }
+  return names;
+}
+
+/** Does this file satisfy the business-error contract? */
+function declaresBusinessErrorContract(content) {
+  if (content.includes(BUSINESS_ERROR_BRAND_TOKEN)) return true;
+  if (!requirePattern('@onlineapps/service-wrapper').test(content)) return false;
+  return destructuredFrom(content, '@onlineapps/service-wrapper')
+    .some(name => WRAPPER_ERROR_NAMES.includes(name));
+}
+
+/**
+ * v1.2 checks: the business-error contract is declared somewhere under src/, and
+ * the retired hierarchy is gone from src/ entirely.
+ *
+ * @param {string} root - Service root
+ * @returns {Array<{ passed: boolean, id: string, message: string, fix?: string }>}
+ */
+function businessErrorChecks(root) {
+  const srcFiles = listJsFiles(root, path.join(root, 'src'));
+
+  let contractFile = null;
+  for (const rel of srcFiles) {
+    const content = readFile(root, rel);
+    if (content && declaresBusinessErrorContract(content)) { contractFile = rel; break; }
+  }
+
+  const contractCheck = contractFile
+    ? {
+      passed: true,
+      id: 'business_error_contract',
+      message: `Business-error contract declared in ${contractFile}`
+    }
+    : {
+      passed: false,
+      id: 'business_error_contract',
+      message: '[ServiceStructureValidator] no business-error contract declared - ' +
+        'nothing under src/ imports a BusinessError family from @onlineapps/service-wrapper ' +
+        'or declares the brand ' + BUSINESS_ERROR_BRAND_TOKEN,
+      fix: 'Throw a contract-carrying error: ' +
+        "const { ValidationError } = require('@onlineapps/service-wrapper'); " +
+        `— or declare Symbol.for('${BUSINESS_ERROR_BRAND_TOKEN}') on the service's own error class.`
+    };
+
+  const offenders = [];
+  for (const rel of listJsFiles(root, path.join(root, 'src'))) {
+    const content = readFile(root, rel);
+    if (!content) continue;
+    const names = destructuredFrom(content, '@onlineapps/service-common')
+      .filter(name => RETIRED_ERROR_NAMES.includes(name));
+    if (names.length > 0) offenders.push({ file: rel, names });
+  }
+
+  const retiredCheck = offenders.length === 0
+    ? {
+      passed: true,
+      id: 'no_retired_error_hierarchy',
+      message: 'No @onlineapps/service-common error-hierarchy import under src/'
+    }
+    : {
+      passed: false,
+      id: 'no_retired_error_hierarchy',
+      message: '[ServiceStructureValidator] retired error hierarchy imported from @onlineapps/service-common - ' +
+        offenders.map(o => `${o.file} imports ${o.names.join(', ')}`).join('; '),
+      fix: offenders
+        .map(o => `Replace in ${o.file} with: const { ${o.names.join(', ')} } = require('@onlineapps/service-wrapper');`)
+        .join(' ')
+    };
+
+  return [contractCheck, retiredCheck];
+}
+
 const STANDARD_LEVELS = [
   {
     level: 'v1.0',
@@ -111,47 +289,7 @@ const STANDARD_LEVELS = [
     level: 'v1.2',
     name: 'Business Error Handling Standard',
     since: '2026-03-24',
-    checks: (root) => {
-      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
-
-      const pkgRaw = read('package.json');
-      let hasServiceCommon = false;
-      if (pkgRaw) {
-        try {
-          const pkg = JSON.parse(pkgRaw);
-          hasServiceCommon = !!pkg.dependencies?.['@onlineapps/service-common'];
-        } catch { /* invalid JSON */ }
-      }
-
-      // ADR 0005 / F6: businessErrorHandler was Express middleware in
-      // src/app.js. Post-F6 there is no src/app.js. Error handling now
-      // happens via BusinessError thrown from handlers → wrapper's
-      // ErrorMapper. Check: at least one handler imports a
-      // BusinessError-family class from @onlineapps/service-common.
-      const handlersDir = path.join(root, 'src', 'handlers');
-      let hasBusinessErrorUsage = false;
-      if (fs.existsSync(handlersDir)) {
-        const walk = (dir) => {
-          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const p = path.join(dir, entry.name);
-            if (entry.isDirectory()) walk(p);
-            else if (entry.isFile() && entry.name.endsWith('.js')) {
-              const content = read(path.relative(root, p));
-              if (content && /@onlineapps\/service-common/.test(content) &&
-                  /BusinessError|ValidationError|NotFoundError|ConflictError|ForbiddenError/.test(content)) {
-                hasBusinessErrorUsage = true;
-              }
-            }
-          }
-        };
-        try { walk(handlersDir); } catch { /* ignore */ }
-      }
-
-      return [
-        { passed: hasServiceCommon, id: 'dep_service_common', message: '@onlineapps/service-common dependency' },
-        { passed: hasBusinessErrorUsage, id: 'business_error_usage', message: 'At least one handler throws a BusinessError family from @onlineapps/service-common' }
-      ];
-    }
+    checks: (root) => businessErrorChecks(root)
   },
   {
     level: 'v1.3',
@@ -272,12 +410,18 @@ class ServiceStructureValidator {
     if (nextLevel) {
       const failing = nextLevel.checks.filter(c => !c.passed);
       for (const check of failing) {
+        // A check that carries its own `fix` has already written a
+        // `[Context] Problem - Expected/Fix` message naming the offending file;
+        // wrapping it in "missing …" would only bury the finding.
         this.warnings.push({
           type: 'STANDARD_LEVEL_GAP',
           level: nextLevel.level,
           check: check.id,
-          message: `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
-          fix: `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/biz/60-templates/service-template.md`
+          message: check.fix
+            ? `Standard ${nextLevel.level} (${nextLevel.name}): ${check.message}`
+            : `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
+          fix: check.fix
+            || `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/biz/60-templates/service-template.md`
         });
       }
     }
@@ -465,7 +609,8 @@ class ServiceStructureValidator {
 
   /**
    * Validate operations.json structure (v3 — handler registry dispatch).
-   * v3 schema per biz-service-invocation-model.md §5.3.
+   *
+   * @see api/docs/biz/30-operations/schema-v3.md § File shape
    */
   validateOperationsStructure(operations) {
     if (!operations.operations) {
@@ -473,7 +618,7 @@ class ServiceStructureValidator {
         type: 'INVALID_OPERATIONS_STRUCTURE',
         path: 'config/service/operations.json',
         message: 'operations.json must have "operations" key',
-        fix: 'Wrap operations in {"operations": {...}}. See: biz-service-invocation-model.md §5.3'
+        fix: 'Wrap operations in {"operations": {...}} in config/service/operations.json'
       });
       return;
     }
@@ -496,7 +641,7 @@ class ServiceStructureValidator {
         field: 'schema_version',
         value: operations.schema_version,
         message: `operations.json schema_version is "${operations.schema_version}" — expected "3.0"`,
-        fix: 'Update schema_version to "3.0" (RFC §5.3)'
+        fix: 'Set schema_version to "3.0" in config/service/operations.json'
       });
     }
 
@@ -518,6 +663,8 @@ class ServiceStructureValidator {
   /**
    * Validate single operation structure (v3).
    * Required: handler, bundle_scope. Forbidden (v2): endpoint, method, path.
+   *
+   * @see api/docs/biz/30-operations/schema-v3.md § Per-operation keys
    */
   validateOperation(name, spec) {
     const requiredFields = ['handler', 'bundle_scope'];
@@ -530,7 +677,7 @@ class ServiceStructureValidator {
           operation: name,
           field,
           message: `Operation "${name}" missing required field: ${field}`,
-          fix: `Add "${field}" to operation "${name}" (v3 schema — RFC §5.3)`
+          fix: `Add "${field}" to operation "${name}" in config/service/operations.json`
         });
       }
     }
@@ -571,7 +718,7 @@ class ServiceStructureValidator {
           field: forbidden,
           value: spec[forbidden],
           message: `Operation "${name}" has retired v2 field "${forbidden}" — not allowed in v3 schema`,
-          fix: `Remove "${forbidden}" — v3 dispatches via handler registry (RFC §5.3, §5.9)`
+          fix: `Remove "${forbidden}" from operation "${name}" in config/service/operations.json — v3 dispatches via the handler registry, not by URL`
         });
       }
     }

package/src/config.js

@@ -1,32 +0,0 @@
-'use strict';
-
-/**
- * Runtime configuration schema for @onlineapps/conn-orch-validator.
- *
- * Uses @onlineapps/runtime-config for unified priority:
- * 1. Explicit config (passed to ValidationOrchestrator/readiness options)
- * 2. Environment variable
- * 3. Module-owned defaults (none for topology)
- *
- * IMPORTANT: Integration test topology is FAIL-FAST (no defaults).
- */
-
-const { createRuntimeConfig } = require('@onlineapps/runtime-config');
-const DEFAULTS = require('./defaults');
-
-const runtimeCfg = createRuntimeConfig({
-  defaults: DEFAULTS,
-  schema: {
-    serviceUrl: { env: 'TEST_SERVICE_URL', required: true },
-    mqUrl: { env: 'TEST_MQ_URL', required: true },
-    registryUrl: { env: 'TEST_REGISTRY_URL', required: true },
-    storageUrl: { env: 'TEST_STORAGE_URL', required: true },
-  }
-});
-
-module.exports = runtimeCfg;
-
-
-
-
-

package/src/defaults.js

@@ -1,11 +0,0 @@
-'use strict';
-
-/**
- * Module-owned defaults for @onlineapps/conn-orch-validator.
- *
- * NOTE: Integration test topology (URLs) is FAIL-FAST and has NO defaults.
- */
-
-module.exports = {};
-
-