@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/cli/oa-validate.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `npx oa-validate [serviceRoot]` — the uniform of a biz service, and
+ * `npx oa-validate --library [packageDir]` — the uniform of a shared library,
+ * checked at any moment in any repository (confirmation `biz-service-manifest`
+ * 001 §3.1, 002 §13.1). One table, exit 0 or 1.
+ *
+ * There is deliberately NO flag that points the run at another manifest and no
+ * flag that skips a row: the manifest ships inside this package and its version
+ * is the pin (`.claude/rules/automation-gates.md` §1 requirement 5 — one path,
+ * unbypassable). `--workspace` is not such a flag: it says WHERE the SSOTs the
+ * manifest references live, and where they cannot be found the rows that need
+ * them are printed NOT RUN, never passed.
+ *
+ * A service run also RECORDS its verdict, in `<serviceRoot>/ci/deployability.json`
+ * — the machine half a deploy gate reads (`deployable && complete`). Until d.232
+ * the only writer was step 7 of the boot validation, which runs inside the
+ * service container, where the workspace SSOTs are absent: every signal that
+ * existed therefore said `complete: false`, so the gate could never see a proven
+ * tree, while the run that IS complete — this CLI, from the api checkout — left
+ * nothing behind. Both callers share one builder and one writer
+ * (`manifest/deployabilitySignal.js`): one file shape, not two.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §3, §4
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
+const { runManifest } = require('../manifest/runManifest');
+const {
+  resolveWorkspaceRoot, canonicalRoot, API_MARKER, PACKAGE_ROOT
+} = require('../manifest/workspaceRoot');
+const {
+  renderReport, renderJson, exitCodeFor, blockingOf, verdictOf, describeClearOutcome
+} = require('../manifest/report');
+const { buildDeployabilitySignal, writeDeployabilitySignal } = require('../manifest/deployabilitySignal');
+const { discoverBearers } = require('../manifest/discovery');
+const { collectRows } = require('../manifest/walk');
+const { CHECK_REGISTRY } = require('../manifest/checks');
+const { declaredCategory, readPackage } = require('../manifest/checks/libraryContext');
+
+/** Exit code for a run that could not start at all — distinct from a finding. */
+const USAGE_EXIT = 2;
+
+/**
+ * This package's own version — the manifest ships inside it, so the manifest
+ * version IS this version (confirmation 004 § point 2).
+ *
+ * Read when the signal is written, not when the module loads: a `require` at the
+ * top would turn a copy of the engine planted without its `package.json` into a
+ * MODULE_NOT_FOUND stack trace before a single row ran, and the reader would be
+ * told nothing about what is missing (`architecture-principles.md` §5). Same
+ * shape, same reason, as `sync/readmeLocation.js` § selfName.
+ *
+ * @returns {string} the version string
+ */
+function validatorVersion() {
+  const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    throw new Error(`[oa-validate] This copy of the engine carries no package.json - ${pkgPath} is missing, `
+      + 'so the deployability signal cannot say which manifest version measured the service. '
+      + 'Fix: run the engine from an installed package or a full checkout of '
+      + 'api/shared/connector/conn-orch-validator.');
+  }
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version;
+}
+
+/** The discovery block of the library uniform — one uniform, one block. */
+const LIBRARY_BLOCK = 'library';
+
+/** The one scope whose `where` is read from the package root rather than the workspace. */
+const PACKAGE_RELATIVE_SCOPE = 'service';
+
+/** What the category column shows for a package that declares none. */
+const NO_CATEGORY = '-';
+
+const USAGE = `
+Usage:
+  oa-validate [serviceRoot] [--workspace <root>] [--json]
+  oa-validate --workspace <root> [--json]
+  oa-validate --library <packageDir> [--workspace <root>] [--json]
+  oa-validate --library --all [--workspace <root>] [--json]
+
+  Checks a repository against the uniform manifest shipped in
+  @onlineapps/conn-orch-validator. The manifest version IS this package's
+  version, so the pin decides which shape the bearer is measured against.
+
+  Three modes, decided by what the run is pointed at:
+    service    — a service root (given, or the current directory) is checked
+                 against the biz-service uniform. Rows that look at the whole
+                 workspace report only what lies under that service; a
+                 neighbour's finding belongs in the neighbour's table.
+    workspace  — NO service root and --workspace <root>: the workspace-wide rows
+                 report in full, and every per-service row is printed NOT RUN,
+                 because there is no repository to look in.
+    library    — --library: the library uniform instead, over one package
+                 directory or, with --all, over every package its discovery
+                 pattern finds.
+
+Arguments:
+  serviceRoot              Biz service repository to check. Default: the current
+                           directory, unless --workspace is given without a service
+                           root, which selects the workspace mode above.
+
+Options:
+  --library [packageDir]   Check a shared library against the library uniform instead.
+                           Give exactly one of: a package directory, or --all.
+  --all                    With --library: every package the uniform's discovery
+                           pattern finds under the workspace root.
+  --workspace <root>       Directory holding the api checkout and its siblings
+                           (api_biz/*), where the manifest's "from" references are
+                           resolved. Default: the parent of the checkout THIS package
+                           lies in — the checkout is found from the package's own
+                           location and carries ${API_MARKER}, whatever it is named.
+                           No such checkout (an installed copy, a service container)
+                           → the rows that need it are reported NOT RUN, never as
+                           passing.
+  --json                   Print the run as JSON instead of the table.
+  --help                   Print this and exit 0.
+
+Output:
+  A service run writes <serviceRoot>/ci/deployability.json — the verdict of the
+  table above in the shape a deploy gate reads (deployable && complete). The
+  workspace and library modes write no such file: the signal is a verdict about
+  one service tree, and neither run has one.
+
+Exit codes:
+  0  no blocking finding (service: boot, deploy | library: publish)
+  1  at least one such finding — the service is not deployable, the library is not publishable
+  2  the run could not start (bad path, broken manifest, no target), or a service
+     run could not record its verdict
+`;
+
+function parseArgs(argv) {
+  const parsed = { serviceRoot: null, workspace: null, json: false, help: false, library: false, all: false };
+  const args = [...argv];
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === '--help' || token === '-h') {
+      parsed.help = true;
+    } else if (token === '--json') {
+      parsed.json = true;
+    } else if (token === '--library') {
+      parsed.library = true;
+    } else if (token === '--all') {
+      parsed.all = true;
+    } else if (token === '--workspace') {
+      const value = args.shift();
+      if (!value || value.startsWith('--')) {
+        throw new Error('[oa-validate] Option --workspace has no value - it names the directory holding '
+          + 'api/ and api_biz/. Fix: oa-validate [serviceRoot] --workspace <root>');
+      }
+      parsed.workspace = value;
+    } else if (token.startsWith('--')) {
+      throw new Error(`[oa-validate] Unknown option - ${token}. Fix: run oa-validate --help for the options.`);
+    } else if (parsed.serviceRoot === null) {
+      parsed.serviceRoot = token;
+    } else {
+      throw new Error(`[oa-validate] Unexpected argument - ${token}. `
+        + 'Fix: exactly one service root is checked per run.');
+    }
+  }
+
+  if (parsed.all && !parsed.library) {
+    throw new Error('[oa-validate] Option --all needs --library - a service is checked one repository at a time. '
+      + 'Fix: oa-validate --library --all');
+  }
+  if (parsed.library && parsed.all && parsed.serviceRoot !== null) {
+    throw new Error(`[oa-validate] --library --all takes no package directory - got ${parsed.serviceRoot}. `
+      + 'Fix: drop the argument, or run oa-validate --library <packageDir> for that one package.');
+  }
+  if (parsed.library && !parsed.all && parsed.serviceRoot === null && !parsed.help) {
+    throw new Error('[oa-validate] --library needs a target - a package directory, or --all for every package '
+      + 'the uniform finds. Fix: oa-validate --library <packageDir> | oa-validate --library --all');
+  }
+
+  return parsed;
+}
+
+/**
+ * Which rows report a path relative to the PACKAGE root, by row id.
+ *
+ * Of the three scopes (`manifestShape.js` § CHECK_SCOPES) only `service` does:
+ * a `scope: workspace` or `scope: bearer` check already writes the path from the
+ * workspace root, precisely so that two packages failing the same row are told
+ * apart (`libraryContext.js` § whereOf). The aggregate run below therefore puts
+ * the package back in front of a `service` row's path and leaves the other two
+ * alone. Asking the registry rather than listing ids keeps this true when a row
+ * changes scope — `L-CONSUMER` and `L-TOOLING` became `bearer` in d.223, and
+ * nothing here had to move.
+ *
+ * @param {object} manifest parsed manifest
+ * @returns {Set<string>} the ids whose `where` is package-relative
+ */
+function packageRelativeRowIds(manifest) {
+  const ids = new Set();
+  for (const { row } of collectRows(manifest)) {
+    if (CHECK_REGISTRY[row.check].scope === PACKAGE_RELATIVE_SCOPE) ids.add(row.id);
+  }
+  return ids;
+}
+
+/**
+ * One package, checked. `runManifest` already places every finding for this
+ * package: a `service` row's path is package-relative, a `bearer` row runs
+ * against this package alone, and a `workspace` row's answer is filtered down to
+ * what lies under this package's root. Nothing is filtered here.
+ *
+ * @param {{ manifest: object, packageRoot: string, workspaceRoot: string|null }} params
+ * @returns {{ findings: Array<object>, notRun: Array<object> }}
+ */
+function checkOnePackage({ manifest, packageRoot, workspaceRoot }) {
+  const result = runManifest({ manifest, serviceRoot: packageRoot, workspaceRoot });
+  const category = declaredCategory(readPackage(packageRoot).json) || NO_CATEGORY;
+
+  return {
+    findings: result.findings.map((finding) => ({ ...finding, category })),
+    notRun: result.notRun
+  };
+}
+
+/**
+ * Every package of the library uniform, checked. Two kinds of run, because the
+ * manifest asks two kinds of question:
+ *
+ *   - one run PER PACKAGE answers the per-package rows, and its `scope: service`
+ *     findings get the package put back in front of their path;
+ *   - one WHOLE-SET run answers the rows that are about the set — `U-ORPHAN`
+ *     reports a name in the SSOT with no package on disk, and that finding
+ *     belongs to no package's root, so no package's run would ever show it.
+ *
+ * The two overlap on the whole-set rows, which every package's run answers
+ * identically; a finding is kept once, keyed by its full identity, so nothing
+ * but an exact repetition collapses. The whole-set run goes last so that a
+ * finding a package already claimed keeps that package's category.
+ *
+ * Discovery is the manifest's, never a second walk: the same pattern and the
+ * same exclusions that decide who wears the uniform decide who is measured
+ * against it.
+ *
+ * @param {{ manifest: object, workspaceRoot: string }} params
+ * @returns {{ findings: Array<object>, notRun: Array<object>, packages: number }}
+ */
+function checkEveryPackage({ manifest, workspaceRoot }) {
+  const block = manifest.discovery[LIBRARY_BLOCK];
+  const { bearers } = discoverBearers({ block, workspaceRoot });
+  const packageRelative = packageRelativeRowIds(manifest);
+
+  const findings = [];
+  const seen = new Set();
+  const notRun = [];
+
+  const keep = (finding) => {
+    const key = `${finding.id}|${finding.where}|${finding.what}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push(finding);
+  };
+
+  for (const bearer of bearers) {
+    const one = checkOnePackage({ manifest, packageRoot: bearer.dir, workspaceRoot });
+    for (const finding of one.findings) {
+      const where = packageRelative.has(finding.id)
+        ? `${bearer.relativeDir}/${finding.where}`
+        : finding.where;
+      keep({ ...finding, where });
+    }
+    for (const skipped of one.notRun) {
+      if (!notRun.some((already) => already.id === skipped.id)) notRun.push(skipped);
+    }
+  }
+
+  // The whole-set run has no package root, so its `scope: service` rows are NOT
+  // RUN by construction — an artefact of this aggregate, not a gap in coverage
+  // (every bearer above ran them). Its `bearer` rows repeat, package by package,
+  // exactly what the loop above already collected, and `keep` drops the
+  // repetition. Only its findings are taken.
+  for (const finding of runManifest({ manifest, workspaceRoot }).findings) {
+    keep({ ...finding, category: NO_CATEGORY });
+  }
+
+  return { findings, notRun, packages: bearers.length };
+}
+
+/** The columns of the library table (002 §13.1). */
+const LIBRARY_COLUMNS = Object.freeze(['id', 'category', 'where', 'what', 'fix']);
+
+function renderLibraryTable(findings) {
+  const widths = LIBRARY_COLUMNS.map((column) => Math.max(
+    column.length,
+    ...findings.map((finding) => String(finding[column]).length)
+  ));
+  const line = (cells) => cells
+    .map((cell, index) => (index === cells.length - 1 ? String(cell) : String(cell).padEnd(widths[index])))
+    .join('  ')
+    .trimEnd();
+
+  return [line(LIBRARY_COLUMNS), ...findings.map((f) => line(LIBRARY_COLUMNS.map((column) => f[column])))];
+}
+
+/**
+ * The library report. Which severities block and which two words the verdict is
+ * printed with come from the LIBRARY manifest, exactly as the service report
+ * takes them from the service one: a library has no boot and no deploy of its
+ * own (002 §10), and a second list in this file was the duplicate that made a
+ * service verdict offer `publish` (`api/shared/TODO.md` §0.2b-15).
+ *
+ * @param {object} run what checkOnePackage or checkEveryPackage returned, plus its heading,
+ *                     the uniform's blockingSeverities and its verdict words
+ * @returns {string} the whole report, newline-terminated
+ */
+function renderLibraryReport(run) {
+  const blocking = blockingOf(run);
+  const verdict = verdictOf(run);
+
+  const lines = [`Library conformance — uniform ${run.uniform}`, ...run.heading, ''];
+
+  for (const skipped of run.notRun) lines.push(`NOT RUN  ${skipped.id} — ${skipped.reason}`);
+  if (run.notRun.length > 0) lines.push('');
+
+  if (run.findings.length > 0) {
+    lines.push(...renderLibraryTable(run.findings), '');
+    lines.push('Doc:');
+    const seen = new Set();
+    for (const finding of run.findings) {
+      if (seen.has(finding.id)) continue;
+      seen.add(finding.id);
+      lines.push(`  ${finding.id}  ${finding.doc}`);
+    }
+    lines.push('');
+  }
+
+  if (blocking.length > 0) {
+    lines.push(`${verdict.blocked} — ${blocking.length} finding(s) of severity `
+      + `${run.blockingSeverities.join('|')}`);
+  } else {
+    // The same sentence the service report prints, from the same owner: a clean
+    // verdict names what did not run (`report.js` § describeClearOutcome).
+    lines.push(`${verdict.clear} — ${describeClearOutcome(run)}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The library modes. Returns the exit code; printing happens here because the
+ * library table has its own columns (002 §13.1) and the service report has its
+ * own owner.
+ *
+ * @param {object} options parsed arguments
+ * @returns {number} exit code
+ */
+function runLibrary(options) {
+  const manifest = loadManifest(LIBRARY_MANIFEST_PATH);
+
+  if (options.all) {
+    const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+    if (workspaceRoot === null) {
+      throw new Error(`[oa-validate] --library --all needs a workspace root - this package lies at ${PACKAGE_ROOT}, `
+        + `which is not shared/connector/<package> of a checkout carrying ${API_MARKER}. `
+        + 'Fix: pass --workspace <root>.');
+    }
+    const run = checkEveryPackage({ manifest, workspaceRoot });
+    const report = {
+      uniform: manifest.uniform,
+      blockingSeverities: manifest.blocking_severities,
+      verdict: manifest.verdict,
+      heading: [`Workspace root: ${workspaceRoot}`, `Packages: ${run.packages}`],
+      ...run
+    };
+    process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderLibraryReport(report));
+    return blockingOf(report).length > 0 ? 1 : 0;
+  }
+
+  const given = path.resolve(options.serviceRoot);
+  if (!fs.existsSync(given) || !fs.statSync(given).isDirectory()) {
+    throw new Error(`[oa-validate] Package directory not found - ${given}. `
+      + 'Fix: pass an existing package directory.');
+  }
+  // The root the run REPORTS is the canonical one, the same spelling the
+  // workspace root is resolved in — so the heading and the engine's own
+  // comparisons speak about one directory (`workspaceRoot.js` § canonicalRoot).
+  const packageRoot = canonicalRoot(given);
+
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+  const run = checkOnePackage({ manifest, packageRoot, workspaceRoot });
+  const report = {
+    uniform: manifest.uniform,
+    blockingSeverities: manifest.blocking_severities,
+    verdict: manifest.verdict,
+    heading: [
+      `Package root: ${packageRoot}`,
+      `Workspace root: ${workspaceRoot === null ? 'NOT RESOLVED' : workspaceRoot}`
+    ],
+    ...run
+  };
+  process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderLibraryReport(report));
+  return blockingOf(report).length > 0 ? 1 : 0;
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    process.stdout.write(`${USAGE.trim()}\n`);
+    return 0;
+  }
+
+  if (options.library) return runLibrary(options);
+
+  const manifest = loadManifest(DEFAULT_MANIFEST_PATH);
+
+  // `--workspace` with no service root IS the workspace mode (lead decision,
+  // api/shared/TODO.md §0.2b-8 point 2): the home of the workspace-wide rows,
+  // the run that sees every orphan rather than only this service's own.
+  if (options.serviceRoot === null && options.workspace !== null) {
+    const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+    const workspaceResult = runManifest({ manifest, workspaceRoot });
+
+    process.stdout.write(options.json ? renderJson(workspaceResult) : renderReport(workspaceResult));
+    return exitCodeFor(workspaceResult);
+  }
+
+  const given = path.resolve(options.serviceRoot === null ? process.cwd() : options.serviceRoot);
+  if (!fs.existsSync(given) || !fs.statSync(given).isDirectory()) {
+    throw new Error(`[oa-validate] Service root not found - ${given}. `
+      + 'Fix: pass an existing repository directory, or run the command inside the service repository.');
+  }
+  const serviceRoot = canonicalRoot(given);
+
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+  const result = runManifest({ manifest, serviceRoot, workspaceRoot });
+
+  process.stdout.write(options.json ? renderJson(result) : renderReport(result));
+
+  // Order as in step 7 (`ValidationOrchestrator.js` § validateManifestConformance):
+  // the report is printed BEFORE the file is written, so a service root that
+  // cannot be written to still leaves the human-readable verdict behind. The
+  // write has no switch — the run that produces the verdict is the run that
+  // records it (`automation-gates.md` §1 requirement 5) — so an unwritable root
+  // ends the run with the writer's own message and the usage exit code, never
+  // with an exit 0 whose signal nobody wrote.
+  writeDeployabilitySignal({
+    serviceRoot,
+    signal: buildDeployabilitySignal({ result, validatorVersion: validatorVersion() })
+  });
+
+  return exitCodeFor(result);
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = USAGE_EXIT;
+  }
+}
+
+module.exports = {
+  main,
+  parseArgs,
+  runLibrary,
+  checkOnePackage,
+  checkEveryPackage,
+  renderLibraryReport,
+  LIBRARY_COLUMNS,
+  USAGE_EXIT
+};

package/src/helpers/README.md

@@ -126,7 +126,16 @@ const operations = JSON.parse(fs.readFileSync(path.join(serviceRoot, 'config/ser
 
 // Extract metadata
 const serviceName = config.service.name;
-const serviceVersion = config.service.version;
+
+// The version comes from package.json, NEVER from config.json. ConfigLoader
+// (shared/connector/service-wrapper/src/ConfigLoader.js) assigns
+// `config.service.version` from package.json unconditionally on every load, and
+// does it BEFORE `${VAR}` placeholders are resolved — so `service.version` in
+// config.json never reaches a running service under any value, and reading it
+// here yielded the literal string `${npm_package_version}`.
+const serviceVersion = JSON.parse(
+  fs.readFileSync(path.join(serviceRoot, 'package.json'), 'utf-8')
+).version;
 ```
 
 Nothing loads `src/app.js` and nothing reads a health endpoint: both belonged to
@@ -164,7 +173,8 @@ function createMyTests(testsDir, options = {}) {
   console.log(ServiceStructureValidator.formatResult(result));
 
   if (!result.valid) {
-    throw new Error('Structure validation failed');
+    throw new Error('[createMyTests] Service structure validation failed - Expected the layout '
+      + 'ServiceStructureValidator requires. Fix: correct the errors printed above, then rerun.');
   }
 
   // 2. Load config

package/src/helpers/createServiceReadinessTests.js

@@ -32,6 +32,48 @@ const ServiceReadinessValidator = require('../ServiceReadinessValidator');
 const MockRegistry = require('../mocks/MockRegistry');
 const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
 const { MIN_COOKBOOK_FORMAT_VERSION } = require('../utils/cookbookFormat');
+const { HANDLER_REF_PATTERN, parseHandlerRef, resolveHandlerModule } = require('../utils/handlerRef');
+
+/**
+ * Resolve every handler an `operations.json` declares, the way the runtime does.
+ *
+ * The readiness suite used to match the ref against a regex and stop there, so
+ * an operation naming a module nobody shipped — or an export that does not
+ * exist — passed readiness in CI and failed at boot, where
+ * `HandlerRegistry.validate()` resolves every declared operation and fail-fasts
+ * (api/docs/biz/10-invocation/handler-dispatch.md § `HandlerRegistry` —
+ * resolution rules). The verdict was right in the end; it arrived one
+ * environment too late.
+ *
+ * Fail-fast on the first unusable handler, naming the operation: a service with
+ * six operations must not report "something is wrong" and leave the reader to
+ * find which.
+ *
+ * @param {string} serviceRoot - absolute path to the service root (holds `src/`)
+ * @param {Object} operationsFlat - the flat `{ name: spec }` map
+ * @returns {Array<{operation: string, modulePath: string, exportName: string, handler: Function}>}
+ * @throws {Error} naming the operation and the reason its handler is unusable
+ */
+function resolveDeclaredHandlers(serviceRoot, operationsFlat) {
+  const resolved = [];
+
+  for (const [operation, spec] of Object.entries(operationsFlat || {})) {
+    try {
+      parseHandlerRef(spec && spec.handler);
+      const { modulePath, exportName, handler } = resolveHandlerModule({
+        serviceRoot,
+        handlerRef: spec.handler
+      });
+      resolved.push({ operation, modulePath, exportName, handler });
+    } catch (error) {
+      throw new Error(
+        `[ServiceReadiness] Operation '${operation}' has an unusable handler - ${error.message}`
+      );
+    }
+  }
+
+  return resolved;
+}
 
 /**
  * Create service readiness integration test suite
@@ -71,7 +113,8 @@ function createServiceReadinessTests(testsDir, options = {}) {
   // FAIL FAST if structure is invalid
   if (!structureResult.valid) {
     throw new Error(
-      `Service structure validation failed. Fix errors above before running tests.`
+      '[createServiceReadinessTests] Service structure validation failed - Expected the layout '
+        + 'ServiceStructureValidator requires. Fix: correct the errors it printed above, then rerun.'
     );
   }
 
@@ -84,9 +127,22 @@ function createServiceReadinessTests(testsDir, options = {}) {
   const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
 
-  // Extract metadata from config
   const serviceName = config.service.name;
-  const serviceVersion = config.service.version;
+
+  // The version comes from package.json, never from config.json — the same
+  // single source of truth the runtime uses:
+  //
+  //   shared/connector/service-wrapper/src/ConfigLoader.js:239
+  //     config.service.version = this.loadPackageVersion(basePath);
+  //
+  // That assignment is unconditional and happens BEFORE `${VAR}` placeholders
+  // are resolved, so `service.version` in config.json never reaches a running
+  // service under any value. Reading it here was reading a dead key, and the
+  // value it yielded was the literal string `${npm_package_version}`: the
+  // placeholder that no expansion pass ever touches, handed to
+  // ServiceReadinessValidator, which used to accept it for being truthy.
+  const packagePath = path.join(serviceRoot, 'package.json');
+  const serviceVersion = JSON.parse(fs.readFileSync(packagePath, 'utf-8')).version;
 
   describe(`${serviceName} Service Readiness @integration`, () => {
     test('service passes readiness validation', async () => {
@@ -175,17 +231,30 @@ function createServiceReadinessTests(testsDir, options = {}) {
       expect(Object.keys(operationsFlat).length).toBeGreaterThan(0);
 
       const validScopes = ['platform', 'tenant', 'workspace'];
-      const handlerPattern = /^handlers\/[a-zA-Z0-9_/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
 
       for (const [, operationSpec] of Object.entries(operationsFlat)) {
         expect(operationSpec).toHaveProperty('handler');
         expect(operationSpec).toHaveProperty('bundle_scope');
-        expect(operationSpec.handler).toMatch(handlerPattern);
+        expect(operationSpec.handler).toMatch(HANDLER_REF_PATTERN);
         expect(validScopes).toContain(operationSpec.bundle_scope);
         expect(operationSpec).not.toHaveProperty('endpoint');
         expect(operationSpec).not.toHaveProperty('method');
       }
     });
+
+    test('every declared handler resolves to an exported function', () => {
+      // The shape of the ref says nothing about whether the module is in the
+      // image. Boot resolves every one of them and refuses to start; this test
+      // asks the same question one environment earlier, by the same rule.
+      const operationsFlat = operations.operations || operations;
+
+      const resolved = resolveDeclaredHandlers(serviceRoot, operationsFlat);
+
+      expect(resolved).toHaveLength(Object.keys(operationsFlat).length);
+      for (const entry of resolved) {
+        expect(typeof entry.handler).toBe('function');
+      }
+    });
   });
 }
 
@@ -218,4 +287,4 @@ function generateMockInput(inputSchema) {
   return mockData;
 }
 
-module.exports = { createServiceReadinessTests };
+module.exports = { createServiceReadinessTests, resolveDeclaredHandlers };