@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/utils/deployContract.js

@@ -1,10 +1,11 @@
 'use strict';
 
 /**
- * Deploy contract checks R1-R7 for a biz service repository.
+ * Deploy contract checks for a biz service repository.
  *
  * Requirements: api/docs/operations/biz-rework-deployment-requirements.md
  * Database rules: ADR 0006 (api/docs/biz/80-decisions/)
+ * R8 permits and their reasons: api/docs/standards/tenant-allocation.md § Enforcement
  *
  *   R1  the production compose pins its image immutably
  *   R2  the deploy resets to origin/production rather than merging
@@ -14,6 +15,11 @@
  *   R7  the CI database engine is the one the service actually talks to
  *   R8  tenant / workspace identity has exactly one source
  *
+ * R6 is absent on purpose: the biz x infra library-compatibility gate lives in
+ * utils/libCompat.js (`verify-lib-compat`), a different command with a different
+ * input. The scope every message prints is rendered from DEPLOY_CONTRACT_SCOPE
+ * below, so it can neither omit a requirement nor claim one that is elsewhere.
+ *
  * Pure module: reads the repository, returns a structured result. It renders
  * nothing and exits nothing — the CLI owns presentation, this owns the rules.
  * That split is what lets the api-side cross-repo audit reuse the same logic
@@ -26,6 +32,41 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * The requirements this module raises, and the ONLY place their extent is
+ * stated. Every message naming the scope renders it from here.
+ *
+ * The list had been written by hand into four messages, which then stopped one
+ * requirement short for months while R8 was already running: the gate announced
+ * less coverage than it enforced, and a reader had no way to tell. `add()` below refuses an
+ * id that is not on this list, so the two cannot drift apart again.
+ */
+const DEPLOY_CONTRACT_REQUIREMENTS = Object.freeze(['R1', 'R2', 'R3', 'R4', 'R5', 'R7', 'R8']);
+
+/**
+ * Render the requirement ids as a scope: consecutive ids collapse into a range,
+ * a gap stays visible ("R1-R5, R7-R8"). The gap is the point — writing "R1-R8"
+ * would claim R6, which this module does not check.
+ *
+ * @param {ReadonlyArray<string>} ids requirement ids, ascending
+ * @returns {string}
+ */
+function formatRequirementScope(ids) {
+  const runs = [];
+  for (const id of ids) {
+    const number = Number(id.slice(1));
+    const open = runs[runs.length - 1];
+    if (open && number === open.end + 1) open.end = number;
+    else runs.push({ start: number, end: number });
+  }
+  return runs
+    .map(({ start, end }) => (start === end ? `R${start}` : `R${start}-R${end}`))
+    .join(', ');
+}
+
+/** "R1-R5, R7-R8" — what the CLI prints, derived, never typed. */
+const DEPLOY_CONTRACT_SCOPE = formatRequirementScope(DEPLOY_CONTRACT_REQUIREMENTS);
+
 const IDENTIFIER_ONLY = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const REQUIRED_MARKER = /[@:]\$\{[A-Za-z_][A-Za-z0-9_]*:\?[^}]*\}$/;
 const BARE_VARIABLE = /\$\{[A-Za-z_][A-Za-z0-9_]*(:-[^}]*)?\}$/;
@@ -285,9 +326,10 @@ function checkDatabaseEngine(serviceRoot, ci, add) {
 //   src/, scripts/          no literal — production code and operational
 //                           scripts take identity from ctx / arguments / env.
 //   tests/integration/      must take the namespace from the repo's shared
-//                           test-namespace module. A positive rule, because the
-//                           literal hides behind any name a test invents
-//                           (`const T = 100`) and pattern-hunting loses.
+//                           test-namespace module, UNLESS it owns its database
+//                           (see the third permit below). A positive rule,
+//                           because the literal hides behind any name a test
+//                           invents (`const T = 100`) and pattern-hunting loses.
 //   config/env-templates/   only shared.env may name the runner namespace.
 //   tests/unit/             exempt — pure in-memory mocks reach no database,
 //                           so a literal there is not a safety boundary, and
@@ -302,16 +344,37 @@ const LITERAL_NAMESPACE = /\b(tenant_id|workspace_id)\s*(?::|={1,3})\s*\d+/;
 const LITERAL_NAMESPACE_CONST =
   /\b(?:const|let|var)\s+[A-Za-z_$][A-Za-z0-9_$]*(?:tenant|workspace)[A-Za-z0-9_$]*\s*=\s*\d+/i;
 
+/** `CREATE DATABASE \`x\``, `create schema x` — the file builds its own schema. */
+const BUILDS_OWN_DATABASE = /\bcreate\s+(?:database|schema)\b/i;
+/** `process.env.DB_NAME = …` and `process.env['DB_NAME'] = …`, assignment only. */
+const REDIRECTS_DB_NAME =
+  /\bprocess\.env\s*(?:\.DB_NAME|\[\s*(['"])DB_NAME\1\s*\])\s*=(?!=)/;
+
+/** `require('@onlineapps/conn-orch-validator')` — the package, not a path inside it. */
+const REQUIRES_VALIDATOR_PACKAGE =
+  /\brequire\(\s*(['"])@onlineapps\/conn-orch-validator\1\s*\)/;
+/** The throwaway-schema build, under the name the package index exports it by. */
+const THROWAWAY_SCHEMA_HELPER = /\bcreateThrowawaySchema\b/;
+
 const SCANNED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.json']);
 const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'coverage', 'dist', 'build']);
 
+/** A call to either library helper: the own namespace, or the foreign one. */
+const NAMESPACE_HELPER_CALL = /\bget(?:Foreign)?TestNamespace\s*\(/;
+
 /** True for the repo's shared test-namespace module, whatever it is named. */
 function isNamespaceModule(relativePath) {
   return /(^|\/)(test-?namespace)[^/]*\.js$/i.test(relativePath);
 }
 
 /**
- * True when the file actually CALLS the shared helper, on a line that executes.
+ * True when the file actually CALLS one of the shared helpers, on a line that
+ * executes — getTestNamespace() for the namespace the test owns,
+ * getForeignTestNamespace() for the one it must not see rows from. Both come
+ * from the library and both return an allowed environment class, so both are
+ * the fix R8 asks for; a test that needs the second one otherwise falls back to
+ * a literal (biz-hello asserted against the live customer tenant 101) or to
+ * arithmetic (99 + 1 = 100, LIVE).
  *
  * The permit used to be a whole-file text match, so a comment saying "TODO:
  * switch to getTestNamespace()" excused the file from R8 entirely — a rule that
@@ -322,7 +385,12 @@ function isNamespaceModule(relativePath) {
 function callsNamespaceHelper(text) {
   return text
     .split('\n')
-    .some((line) => !isCommentLine(line) && /\bgetTestNamespace\s*\(/.test(line));
+    .some((line) => !isCommentLine(line) && NAMESPACE_HELPER_CALL.test(line));
+}
+
+/** True when `pattern` matches on a line that executes, not one that describes. */
+function matchesOnExecutingLine(text, pattern) {
+  return text.split('\n').some((line) => !isCommentLine(line) && pattern.test(line));
 }
 
 /** A literal inside a comment is prose — it cannot reach a database. */
@@ -331,6 +399,77 @@ function isCommentLine(line) {
   return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
 }
 
+/**
+ * The other half of the same distinction. A comment is prose because of WHERE
+ * it sits; an error message is prose because of WHAT IT SAYS.
+ *
+ * "Inside quotes" alone is NOT the test, and must never become it: a query is
+ * a string too, and a query is exactly what reaches a database —
+ * `SELECT 1 FROM t WHERE tenant_id = 100` has to keep failing. What separates
+ * the two is the verb. Prose makes a CLAIM about the identifier ("workspace_id
+ * = 0 IS NOT a value"); code assigns a VALUE to it, and nothing follows the
+ * number but syntax.
+ *
+ * So the permit is granted only when the number is followed, inside the same
+ * string literal, by a finite verb from the closed list below. Everything else
+ * — end of string, `,`, `)`, ` AND `, ` order by ` — stays reported. The list
+ * is deliberately short and enumerated rather than clever: a gate whose verdict
+ * cannot be predicted from reading it is not a gate (`automation-gates.md` §1).
+ *
+ * Both conditions fail CLOSED. A string that spans several lines looks to this
+ * line-local scanner like no string at all, so its literal keeps its report.
+ */
+const PROSE_PREDICATE =
+  /^[\s,;:—-]*\b(is|are|was|were|has|have|had|means|meant|carries|carry|cannot|must|never|does|do|would|will|remains|stays)\b/i;
+
+/**
+ * The end offset of the CLOSED string literal containing `index`, or -1 when
+ * that position is code. Line-local and escape-aware; a quote opened on an
+ * earlier line is invisible here, which is the safe direction (no permit).
+ */
+function enclosingStringEnd(line, index) {
+  let quote = null;
+  let start = -1;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (quote !== null && ch === '\\') { i += 1; continue; }
+    if (quote === null) {
+      if (ch === "'" || ch === '"' || ch === '`') { quote = ch; start = i; }
+    } else if (ch === quote) {
+      if (index > start && index < i) return i;
+      quote = null;
+      start = -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * True when the literal at `index` is quoted inside an English sentence that
+ * talks ABOUT the identifier, rather than handing it a value.
+ */
+function isProseLiteral(line, index, matchText) {
+  const end = enclosingStringEnd(line, index);
+  if (end === -1) return false;
+  return PROSE_PREDICATE.test(line.slice(index + matchText.length, end));
+}
+
+/**
+ * A tenant / workspace identity frozen into this line of executable code.
+ *
+ * One rail for both scan sites (src+scripts, and the shared test-namespace
+ * module), so the two permits — comment, prose — cannot drift apart.
+ */
+function freezesNamespaceIdentity(line) {
+  if (isCommentLine(line)) return false;
+  for (const pattern of [LITERAL_NAMESPACE, LITERAL_NAMESPACE_CONST]) {
+    const match = pattern.exec(line);
+    if (!match) continue;
+    if (!isProseLiteral(line, match.index, match[0])) return true;
+  }
+  return false;
+}
+
 function walkFiles(dir, base, out) {
   let entries;
   try {
@@ -384,8 +523,7 @@ function checkNamespaceLiterals(serviceRoot, add) {
       if (text === null) continue;
       const lines = text.split('\n');
       for (let i = 0; i < lines.length; i += 1) {
-        if (isCommentLine(lines[i])) continue;
-        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        if (!freezesNamespaceIdentity(lines[i])) continue;
         add('R8', `${file.relative}:${i + 1} freezes a tenant / workspace id into code:\n`
           + `       ${lines[i].trim()}\n`
           + '       Fix: take it from ctx (handlers), from a CLI argument (scripts),\n'
@@ -409,8 +547,7 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
     if (isNamespaceModule(file.relative)) {
       const lines = text.split('\n');
       for (let i = 0; i < lines.length; i += 1) {
-        if (isCommentLine(lines[i])) continue;
-        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        if (!freezesNamespaceIdentity(lines[i])) continue;
         add('R8', `${file.relative}:${i + 1} freezes the test namespace into a literal:\n`
           + `       ${lines[i].trim()}\n`
           + '       This module exists so the namespace has one source; that source must\n'
@@ -426,6 +563,61 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
     // that itself reads the platform env (checked above).
     if (callsNamespaceHelper(text)) continue;
     if (/require\([^)]*test-?namespace[^)]*\)/i.test(text)) continue;
+
+    // Third permit — the file builds its throwaway through the library.
+    //
+    // `utils/throwawaySchema.js` is the one build for every DB-owning service:
+    // it refuses the schema the service declares, drops and recreates the
+    // throwaway it was given, names that schema on every statement, and strips
+    // the schema selects out of the migrations so a `USE oagen_<service>` line
+    // written for the install runner cannot redirect them. Where those
+    // statements land is therefore decided by code, not inferred from two
+    // strings — which is the whole difference between this permit and the one
+    // below it.
+    //
+    // Both halves are required and both on a line that executes: the package
+    // import AND the helper. A repo-local module that happens to export the same
+    // name earns nothing, because what is being trusted here is this package's
+    // build and nothing else (`automation-gates.md` §5 — a rule a mention
+    // satisfies checks nothing).
+    if (matchesOnExecutingLine(text, REQUIRES_VALIDATOR_PACKAGE)
+      && matchesOnExecutingLine(text, THROWAWAY_SCHEMA_HELPER)) {
+      continue;
+    }
+
+    // Fourth permit — the file owns its database.
+    //
+    // The shared-namespace rule assumes the test writes into the service's live
+    // schema, where the namespace IS the safety boundary. A test that builds a
+    // throwaway database and drops it targets no shared namespace, so neither
+    // permit above means anything for it: the assertion "my identity does not
+    // collide with the test namespace" cannot fail, because getTestNamespace()
+    // only ever returns a value from ALLOWED_TENANT_CLASSES. A requirement whose
+    // only available compliance is an assertion that cannot fail documents no
+    // fix at all, and `automation-gates.md` §3 forbids reporting such a state.
+    //
+    // What decides where those queries land is DB_NAME, so that is what the
+    // permit asks for — positively, like the rest of R8, and not as a deny-list
+    // of the live database name: naming one database to avoid protects that one
+    // and nothing else (api/docs/standards/tenant-allocation.md § Enforcement).
+    // Both halves must be earned on a line that executes; a rule a mention
+    // satisfies checks nothing (`automation-gates.md` §5).
+    if (matchesOnExecutingLine(text, BUILDS_OWN_DATABASE)) {
+      if (matchesOnExecutingLine(text, REDIRECTS_DB_NAME)) continue;
+      add('R8', `${file.relative} creates its own database but never redirects DB_NAME to it.\n`
+        + '       The schema it builds is therefore not the schema its queries reach:\n'
+        + '       the service config still points at the live database, so the test\n'
+        + '       writes there while appearing to own a throwaway.\n'
+        + '       Expected: a file that builds its own schema also directs the service\n'
+        + '       at it, so nothing it runs can land in live data.\n'
+        + "       Fix: set process.env.DB_NAME to that schema before the first require\n"
+        + '       of the service\'s database config; or, if the file does target the\n'
+        + '       shared namespace after all, take it from the repo\'s\n'
+        + '       tests/integration/testNamespace.js instead.\n'
+        + '       Rule: api/docs/standards/tenant-allocation.md § Enforcement');
+      continue;
+    }
+
     add('R8', `${file.relative} names a tenant / workspace without taking it from the\n`
       + '       shared test-namespace module.\n'
       + '       An integration test writes into a real database, so the namespace it\n'
@@ -436,7 +628,7 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
 }
 
 /**
- * Verify one biz repository against R1-R8.
+ * Verify one biz repository against the deploy contract.
  *
  * @param {string} serviceRoot absolute path to the biz repo
  * @returns {{service: string, ok: boolean, violations: Array<{requirement: string, message: string}>}}
@@ -451,7 +643,15 @@ function verifyDeployContract(serviceRoot) {
   }
 
   const violations = [];
-  const add = (requirement, message) => violations.push({ requirement, message });
+  const add = (requirement, message) => {
+    if (!DEPLOY_CONTRACT_REQUIREMENTS.includes(requirement)) {
+      throw new Error(`[DeployContract] Unknown requirement "${requirement}" - Expected one of `
+        + `${DEPLOY_CONTRACT_REQUIREMENTS.join(', ')}. Fix: add the id to `
+        + 'DEPLOY_CONTRACT_REQUIREMENTS in utils/deployContract.js, so the scope every message '
+        + 'reports stays this module\'s own list.');
+    }
+    violations.push({ requirement, message });
+  };
 
   const compose = readIfExists(path.join(serviceRoot, 'docker-compose.production.yml'));
   if (compose === null) {
@@ -485,4 +685,4 @@ function verifyDeployContract(serviceRoot) {
   };
 }
 
-module.exports = { verifyDeployContract };
+module.exports = { verifyDeployContract, DEPLOY_CONTRACT_REQUIREMENTS, DEPLOY_CONTRACT_SCOPE };

package/src/utils/envContract.js

@@ -331,6 +331,52 @@ function collectEnvReads({ serviceRoot }) {
   return { reads, dynamicSites, filesScanned: files.length };
 }
 
+/**
+ * Principle 4: the completeness gate validates its own input before it judges.
+ *
+ * Both arguments used to be read on trust. Handed the loader envelope
+ * (`{serviceRoot, contractPath, contract}`) in place of the normalized contract,
+ * the scan found neither `requiredConnectors` nor `env`, so it compared the
+ * repository against an EMPTY declaration with no connector coverage — and over
+ * a repository whose reads are all M1-covered it answered `ok: true`. That is a
+ * PASS printed over a declaration the gate never read, which is the false
+ * guarantee automation-gates.md §5 calls a defect of the same severity as a
+ * wrong result (BIZ-pdfgen, 2026-08-28).
+ *
+ * The shape is not restated here. `requiredConnectors` is judged against the
+ * connector set this module already reads for M2 coverage, and the env block
+ * against `normalizeEnvDeclaration` (below, in verifyEnvCompleteness) — one
+ * definition each, no second copy to drift.
+ */
+function assertNormalizedContract(contract) {
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) {
+    throw new Error('[EnvContract] Invalid contract - Expected the normalized integration contract object, '
+      + `got ${Array.isArray(contract) ? 'an array' : typeof contract}. `
+      + 'Fix: pass loadAndValidateIntegrationContract(serviceRoot).contract, not the envelope around it.');
+  }
+
+  const connectors = contract.requiredConnectors;
+  const missing = !connectors || typeof connectors !== 'object' || Array.isArray(connectors)
+    ? Object.keys(CONNECTORS)
+    : Object.keys(CONNECTORS).filter((name) => typeof connectors[name] !== 'boolean');
+
+  if (missing.length > 0) {
+    throw new Error('[EnvContract] Invalid contract - requiredConnectors does not declare a boolean for '
+      + `${missing.join(', ')}, so this is not a normalized integration contract. `
+      + 'Fix: pass loadAndValidateIntegrationContract(serviceRoot).contract — the loader envelope it is '
+      + 'wrapped in carries the contract under .contract, and checking against the envelope reads an '
+      + 'empty declaration as a satisfied one.');
+  }
+}
+
+/** The scan reads the repository off disk, so the root has to be a path. */
+function assertScannableServiceRoot(serviceRoot) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.trim() === '') {
+    throw new Error('[EnvContract] Invalid serviceRoot - Expected a non-empty path to the repository root, '
+      + `got ${typeof serviceRoot}. Fix: pass loadAndValidateIntegrationContract(serviceRoot).serviceRoot.`);
+  }
+}
+
 /**
  * COMPLETENESS: every environment name the repository visibly reads is either
  * declared in the env block or covered by M1/M2.
@@ -343,14 +389,24 @@ function collectEnvReads({ serviceRoot }) {
  *            dynamicSites: Array<{file: string, line: number}>}}
  */
 function verifyEnvCompleteness({ serviceRoot, contract }) {
+  assertScannableServiceRoot(serviceRoot);
+  assertNormalizedContract(contract);
+
   const coverage = collectEnvCoverage({
     serviceRoot,
     requiredConnectors: contract.requiredConnectors
   });
 
+  // The declaration is re-derived through the function that DEFINES it rather
+  // than read field by field: an env block that never went through
+  // normalizeEnvDeclaration is refused here instead of being silently counted
+  // as whatever `?.[listKey] ?? []` happens to find in it. A normalized block
+  // round-trips unchanged — same repository, same coverage, same result.
+  const declaration = normalizeEnvDeclaration(contract.env, { coverage });
+
   const declared = new Set();
   for (const listKey of ENV_LIST_KEYS) {
-    for (const item of contract.env?.[listKey] ?? []) declared.add(item.name);
+    for (const item of declaration?.[listKey] ?? []) declared.add(item.name);
   }
 
   const { reads, dynamicSites, filesScanned } = collectEnvReads({ serviceRoot });

package/src/utils/handlerRef.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * What a v3 handler reference IS, and what resolving one MEANS — one definition
+ * for the whole package, and the one the wrapper can adopt.
+ *
+ * Before this module the rule lived in five places. Four of them were copies of
+ * the same regex literal checking only the shape (`ServiceReadinessValidator`,
+ * `ValidationOrchestrator`, `ServiceStructureValidator`,
+ * `helpers/createServiceReadinessTests`); the fifth,
+ * `CookbookTestRunner.resolveOperation`, resolved a ref for real and did it
+ * more weakly than production: it split on `#` without counting the separators,
+ * so `a#b#c` was silently truncated, and it joined the path onto
+ * `<serviceRoot>/src` with no containment check, so `../outside#run` loaded and
+ * ran a module from outside the service source root. A second implementation of
+ * one concern is a defect by default (`change-discipline.md` § One rail per
+ * concern), and the weaker one had been the one dispatching cookbooks.
+ *
+ * The two exported functions are deliberately separate, and the split is what
+ * lets `service-wrapper`'s `HandlerLoader` take this over as an internal swap
+ * rather than an API change:
+ *
+ *   - `parseHandlerRef` states the DECLARED FORM. `handlers/<path>#<export>` is
+ *     owned by api/docs/biz/30-operations/schema-v3.md § handler, and every
+ *     shape check in this package now reads `HANDLER_REF_PATTERN` instead of
+ *     restating it.
+ *   - `resolveHandlerModule` states RESOLUTION: containment inside
+ *     `<serviceRoot>/src`, `require`, and an export that is a function. It does
+ *     NOT demand the declared form, because `HandlerLoader.resolve()` accepts
+ *     any relative path inside the source root today — narrowing that is a
+ *     contract decision for the owner (`confirmation-triggers.md` §1.2), never
+ *     a side effect of sharing code.
+ *
+ * Layer: L3 (Orchestration). Filesystem + require only, no cross-imports.
+ *
+ * @see api/docs/biz/10-invocation/handler-dispatch.md § `HandlerRegistry` — resolution rules
+ * @see api/docs/biz/30-operations/schema-v3.md § handler
+ */
+
+const path = require('path');
+
+/**
+ * The declared form of a handler ref — the single literal in this package.
+ * The path charset carries no `.`, which is why a conformant ref can express
+ * neither a file extension nor a `..` traversal.
+ */
+const HANDLER_REF_PATTERN = /^handlers\/[a-zA-Z0-9_/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** How the ref is printed back to whoever has to fix it. */
+function printRef(value) {
+  return typeof value === 'string' ? `"${value}"` : String(value);
+}
+
+/**
+ * The arity rule, shared by both exported functions: exactly one `#`, both
+ * halves non-empty. Kept private so there is one place that counts separators.
+ *
+ * @param {string} handlerRef
+ * @returns {{relPath: string, exportName: string}}
+ */
+function splitHandlerRef(handlerRef) {
+  if (typeof handlerRef !== 'string' || handlerRef.length === 0) {
+    throw new Error(
+      `[HandlerRef] handlerRef must be a non-empty string - Got: ${printRef(handlerRef)}. `
+      + 'Fix: declare handler as "handlers/<path>#<exportName>" in config/service/operations.json.'
+    );
+  }
+
+  const segments = handlerRef.split('#');
+  if (segments.length !== 2) {
+    throw new Error(
+      `[HandlerRef] handlerRef contains ${segments.length - 1} '#' separators - Expected exactly `
+      + `one, as "handlers/<path>#<exportName>". Got: '${handlerRef}'. `
+      + 'Fix: correct the handler ref in config/service/operations.json.'
+    );
+  }
+
+  const [relPath, exportName] = segments;
+  if (!relPath || !exportName) {
+    throw new Error(
+      '[HandlerRef] handlerRef has an empty half - Expected "<relative/path>#<exportName>" '
+      + `with both sides non-empty. Got: '${handlerRef}'. `
+      + 'Fix: correct the handler ref in config/service/operations.json.'
+    );
+  }
+
+  return { relPath, exportName };
+}
+
+/**
+ * Parse a handler ref against the DECLARED FORM.
+ *
+ * @param {string} handlerRef - as written in `config/service/operations.json`
+ * @returns {{relPath: string, exportName: string}} path relative to `src/`, and the named export
+ * @throws {Error} when the ref is absent, malformed, or outside the declared form
+ */
+function parseHandlerRef(handlerRef) {
+  const parts = splitHandlerRef(handlerRef);
+
+  if (!HANDLER_REF_PATTERN.test(handlerRef)) {
+    throw new Error(
+      '[HandlerRef] handlerRef does not match the declared form - Expected '
+      + '"handlers/<path>#<exportName>" (path relative to src/, no file extension). '
+      + `Got: '${handlerRef}'. Fix: correct the handler ref in config/service/operations.json `
+      + '- see api/docs/biz/30-operations/schema-v3.md § handler.'
+    );
+  }
+
+  return parts;
+}
+
+/**
+ * Resolve a handler ref to the exported function, the way the runtime does.
+ *
+ * The containment check runs on the RESOLVED location, not on the spelling of
+ * the reference, so `..` segments and an absolute path are both caught; the
+ * prefix carries the separator so a prefix-named sibling (`src-evil` beside
+ * `src`) cannot pass as a child. It is lexical — a symlink inside the source
+ * root pointing out of it is not detected, exactly as in `HandlerLoader`.
+ *
+ * @param {Object} args
+ * @param {string} args.serviceRoot - absolute path to the service root (holds `src/`)
+ * @param {string} args.handlerRef - `<relative/path>#<exportName>`
+ * @returns {{modulePath: string, exportName: string, handler: Function}}
+ * @throws {Error} when the ref escapes the source root, the module does not
+ *   load, or the named export is not a function
+ */
+function resolveHandlerModule({ serviceRoot, handlerRef } = {}) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.length === 0) {
+    throw new Error(
+      '[HandlerRef] serviceRoot is required - Expected an absolute path to the service root '
+      + `(the directory holding src/). Got: ${serviceRoot}.`
+    );
+  }
+  if (!path.isAbsolute(serviceRoot)) {
+    throw new Error(
+      `[HandlerRef] serviceRoot must be absolute - Got: ${serviceRoot}. `
+      + 'Fix: pass the resolved service root (path.resolve of the directory holding src/).'
+    );
+  }
+
+  const { relPath, exportName } = splitHandlerRef(handlerRef);
+
+  const baseDir = path.resolve(serviceRoot, 'src');
+  const baseDirPrefix = path.join(baseDir, path.sep);
+  const absModule = path.resolve(baseDir, relPath);
+  if (!absModule.startsWith(baseDirPrefix)) {
+    throw new Error(
+      `[HandlerRef] handlerRef escapes the service source root - '${handlerRef}' resolves to `
+      + `'${absModule}', outside '${baseDir}'. Fix: use a path inside the service source root `
+      + '(no ".." segments, not absolute).'
+    );
+  }
+
+  let modulePath;
+  let mod;
+  try {
+    modulePath = require.resolve(absModule);
+    mod = require(modulePath);
+  } catch (error) {
+    throw new Error(
+      `[HandlerRef] Failed to require '${absModule}' resolved from '${handlerRef}' - `
+      + 'Expected a loadable module at that path. Fix: ship the module in the service, or '
+      + `correct the handler ref in config/service/operations.json. Cause: ${error.message}`
+    );
+  }
+
+  const handler = mod[exportName];
+  if (typeof handler !== 'function') {
+    throw new Error(
+      `[HandlerRef] Export '${exportName}' is not a function in '${modulePath}' - Expected the `
+      + `module to expose '${exportName}' as a function (the ref '${handlerRef}' names it). `
+      + `Fix: make '${exportName}' a function in that module, or correct the handler ref in `
+      + 'config/service/operations.json.'
+    );
+  }
+
+  return { modulePath, exportName, handler };
+}
+
+module.exports = { HANDLER_REF_PATTERN, parseHandlerRef, resolveHandlerModule };