@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/utils/cookbookFormat.js

@@ -1,23 +1,23 @@
 'use strict';
 
 /**
- * Cookbook format rule — the single place in this package that decides which
- * cookbook format version the platform accepts.
+ * Cookbook format helpers this package still owns — what
+ * `@onlineapps/cookbook-core` `validateCookbook` does not do.
  *
- * The rule itself is owned by the biz doc tree, not by this file:
- * api/docs/biz/40-cookbooks/format.md § "Required fields" — `version` is a
- * REQUIRED string, `"2.1.0"` or higher. This module only implements that
- * sentence so both entry points enforce the same thing:
+ * The format rules themselves (`version`, the `steps` array, a step's
+ * `step_id`/`type`/`service`/`operation`) are cookbook-core's; both entry
+ * points of this package run it FIRST — the Tier-1 gate
+ * (`CookbookTestRunner.validateCookbook()`, d.980) and the readiness-wrapper
+ * path (`CookbookTestUtils.validateCookbook()`, d.984). Copies of its rules
+ * went with their last readers: `checkCookbookFormatVersion` (the version rule)
+ * in d.984, and the ban on a step key `id` in d.985 — cookbook-core refuses it
+ * since d.983 (`Forbidden field 'id' at /steps/<n>/id`).
  *
- *   - `CookbookTestRunner.validateCookbook()` — the Tier-1 gate every biz
- *     service runs at boot (mandatory, no per-repo opt-in);
- *   - `CookbookTestUtils.validateCookbook()` — the readiness-wrapper path
- *     three repos still call from `tests/bootstrap/service-readiness.test.js`.
- *
- * Returned messages carry the `Problem - Expected/Fix` part of the error
- * format (architecture-principles §5); the `[Context]` prefix belongs to the
- * caller, which is the one that knows whether it read a file or was handed an
- * object.
+ * What stays is read by code that holds a cookbook nobody has validated yet
+ * (`CookbookTestUtils.compareCookbooks`, `CookbookTestRunner._operationsOf`,
+ * `hasExpectClauses`): `readCookbookSteps`, which hands over the steps as the
+ * array they must be; `stepIdentityOf`; and `MIN_COOKBOOK_FORMAT_VERSION`, the
+ * version this package writes into the cookbooks it synthesises.
  *
  * @see api/docs/biz/40-cookbooks/format.md
  * @see api/docs/biz/40-cookbooks/test-runner-flow.md
@@ -27,21 +27,7 @@
 const MIN_COOKBOOK_FORMAT_VERSION = '2.1.0';
 
 /**
- * `major.minor.patch`, digits only, all three components required.
- *
- * The machine SSOT is `shared/cookbook/cookbook-core/schemas/cookbook.v2.schema.json:16`
- * — `"pattern": "^2\\.\\d+\\.\\d+$"`. Until 2026-09-05 this gate accepted 1 to 3
- * components, so `"version": "2.1"` passed Tier-1 here and failed schema
- * validation there: two rails, two answers, the offline one lenient. The major
- * is deliberately NOT pinned to 2 here — that ceiling belongs to the schema; the
- * floor this module owns is `MIN_COOKBOOK_FORMAT_VERSION`.
- */
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
-
-const DOC_REFERENCE = 'api/docs/biz/40-cookbooks/format.md § Required fields';
-
-/**
- * The same node, § The array is the only accepted shape — the section that owns
+ * The format node's section `The array is the only accepted shape` owns
  * both halves of the rule below: `steps` is an array, and a step identifies
  * itself with `step_id`. The node has no section called `Steps`; this constant
  * named one until 2026-09-14, and `L008` never noticed, because it checks the
@@ -52,63 +38,6 @@ const STEPS_DOC_REFERENCE = 'api/docs/biz/40-cookbooks/format.md § The array is
 /** `2.1` — how the format version is spoken about in prose, derived, never typed twice. */
 const MIN_FORMAT_MAJOR_MINOR = MIN_COOKBOOK_FORMAT_VERSION.split('.').slice(0, 2).join('.');
 
-/**
- * @param {string} version numeric version string, already pattern-checked
- * @returns {number[]} exactly three components, missing ones are 0
- */
-function toComponents(version) {
-  const parts = version.split('.').map((part) => parseInt(part, 10));
-  while (parts.length < 3) {
-    parts.push(0);
-  }
-  return parts;
-}
-
-/**
- * @param {string} a numeric version string
- * @param {string} b numeric version string
- * @returns {number} negative when a < b, 0 when equal, positive when a > b
- */
-function compareVersions(a, b) {
-  const left = toComponents(a);
-  const right = toComponents(b);
-
-  for (let i = 0; i < 3; i++) {
-    if (left[i] !== right[i]) {
-      return left[i] - right[i];
-    }
-  }
-  return 0;
-}
-
-/**
- * Check a cookbook's `version` field against the documented format rule.
- *
- * @param {*} version the raw value of the cookbook's top-level `version`
- * @returns {string|null} `null` when the version satisfies the rule, otherwise
- *   the problem in `Problem - Expected/Fix` form
- */
-function checkCookbookFormatVersion(version) {
-  if (version === undefined || version === null || version === '') {
-    return `cookbook format version is missing - Expected top-level "version": "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
-      + `Fix: add "version": "${MIN_COOKBOOK_FORMAT_VERSION}" to the cookbook (${DOC_REFERENCE}).`;
-  }
-
-  if (typeof version !== 'string' || !VERSION_PATTERN.test(version)) {
-    return `cookbook format version ${JSON.stringify(version)} is not a version string - `
-      + `Expected numeric "<major>.<minor>.<patch>", "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
-      + `Fix: write the version as "${MIN_COOKBOOK_FORMAT_VERSION}" (${DOC_REFERENCE}).`;
-  }
-
-  if (compareVersions(version, MIN_COOKBOOK_FORMAT_VERSION) < 0) {
-    return `cookbook format version "${version}" is below the required minimum ${MIN_COOKBOOK_FORMAT_VERSION} - `
-      + `Expected "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
-      + `Fix: migrate the cookbook to the v2.1 format and set "version": "${MIN_COOKBOOK_FORMAT_VERSION}" (${DOC_REFERENCE}).`;
-  }
-
-  return null;
-}
-
 /**
  * @param {*} steps a `steps` value that is neither an array nor absent
  * @returns {string} the shape, worded for the refusal message
@@ -118,19 +47,17 @@ function describeStepsShape(steps) {
 }
 
 /**
- * Read a cookbook's `steps` in the ONE shape the format allows — an array of
- * step objects, each carrying `step_id` — and refuse everything else.
- *
- * Two refusals, one rule each:
+ * Read a cookbook's `steps` in the ONE shape the format allows — an array —
+ * and refuse any other shape.
  *
- * 1. **Any shape but an array.** Owner decision 2026-09-05, fully authoritative
+ * **Any shape but an array.** Owner decision 2026-09-05, fully authoritative
  *    (`api/docs/governance/confirmations/cookbook-steps-shape.md` 001): `steps`
  *    is an ARRAY, the only allowed shape, and the object variant "must not be
  *    permitted or used anywhere". It supersedes the 2026-08-17 object
  *    directive, which never landed in any runtime. The reason is order:
  *    JavaScript reorders numeric object keys and Postgres `jsonb` does not
  *    preserve key order either (measured M9,
- *    `infra/api_monitoring/src/consumer/cookbookSplit.js:32-37`), so an
+ *    `infra/api_monitoring/src/consumer/cookbookSplit.js`, `canonicalize`), so an
  *    object-keyed cookbook has no defined execution order at all. Arrays keep
  *    theirs, because a reordered step list IS a different cookbook.
  *
@@ -139,22 +66,16 @@ function describeStepsShape(steps) {
  *    gate accepted a cookbook the production WorkflowOrchestrator — which only
  *    ever read arrays — threw on.
  *
- * 2. **A step spelling its identifier `id`.** The node bans it outright
- *    (format.md § The array is the only accepted shape). Silently reading `id`
- *    is the fallback
- *    `architecture-principles.md` §3 forbids, and it hides an authoring mistake
- *    until something downstream reports `Step undefined`. There is no `id`
- *    anywhere any more: the adapter that wrote `id = step_id` went with
- *    `@onlineapps/cookbook-executor` (deleted 2026-08-31), and
- *    WorkflowOrchestrator — the single owner of cookbook execution — reads
- *    `step_id`.
+ * What a step inside the array may carry is cookbook-core's to judge, not this
+ * function's: until d.985 it also refused a step spelling its identifier `id`,
+ * a copy of the rule cookbook-core has owned since d.983.
  *
  * An absent `steps` is NOT a shape problem: the caller owns that message,
  * because only it knows whether it is reading a file or an object handed to it.
  *
  * @param {*} steps the raw value of the cookbook's top-level `steps`
  * @returns {object[]} the steps, unchanged; `[]` when `steps` is absent
- * @throws {Error} when `steps` is present but not an array, or a step carries `id`
+ * @throws {Error} when `steps` is present but not an array
  */
 function readCookbookSteps(steps) {
   if (steps === undefined || steps === null) {
@@ -174,22 +95,12 @@ function readCookbookSteps(steps) {
     );
   }
 
-  steps.forEach((step, index) => {
-    if (step && typeof step === 'object' && 'id' in step) {
-      const label = stepIdentityOf(step) || `#${index + 1}`;
-      throw new Error(
-        `[CookbookFormat] step "${label}" carries "id" - Expected: "step_id" only `
-        + `(${STEPS_DOC_REFERENCE}). Fix: rename "id" to "step_id"`
-      );
-    }
-  });
-
   return steps;
 }
 
 /**
  * The identifier a step declares. `step_id` is the ONLY spelling the format
- * allows; `readCookbookSteps` refuses a step that carries `id`, so nothing
+ * allows; cookbook-core refuses a step that carries `id` (d.983), so nothing
  * downstream needs to know that name ever existed.
  *
  * @param {object} step one normalised step
@@ -207,7 +118,6 @@ function stepIdentityOf(step) {
 
 module.exports = {
   MIN_COOKBOOK_FORMAT_VERSION,
-  checkCookbookFormatVersion,
   readCookbookSteps,
   stepIdentityOf
 };

package/src/utils/dbAccountGrants.js

@@ -42,9 +42,11 @@
  * schema name before either statement is built; the production runbook
  * (`api/docs/setup/INSTALL.md` § the account and its grants, `schema_grant`)
  * already escaped it, and a definition laxer than the runbook installing from it
- * is the wrong way round. Measured against the dev server in
- * `tests/unit/bizCiGateCli.setupDbAccount.integration.test.js`: with the
- * unescaped grant the account reads the neighbour's rows; with it, `ERROR 1142`.
+ * is the wrong way round. What the server does with it is measured on a real
+ * MariaDB by `tests/unit/bizCiGateCli.setupDbAccount.integration.test.js`,
+ * describe block `the production grant on a real MariaDB — how far it reaches
+ * @integration`: the escaped grant refuses the neighbour that differs in that
+ * one character with `ERROR 1142`, and still reaches its own schema.
  *
  * `%` — the other wildcard of that position — is REFUSED rather than escaped,
  * for the reason the comment above `FORBIDDEN_IN_VALUE` gives: no platform

package/src/utils/deployContract.js

@@ -33,6 +33,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { topLevelKeys, topLevelKeyAt } = require('./yamlTopLevel');
+
 /**
  * The requirements this module raises, and the ONLY place their extent is
  * stated. Every message naming the scope renders it from here.
@@ -156,7 +158,10 @@ function checkPublishedPorts(compose, add) {
 //
 //   the ancestor check — a commit that is not on the branch this box follows is
 //   a pipeline for a different history, and resetting to it puts the box on code
-//   production never took. Fail-fast, before anything is touched.
+//   production never took. Fail-fast, before anything is touched — and in the
+//   SAME JOB as the reset, because the job is the shell: a check standing in a
+//   different job did not run when this reset ran, however early in the file it
+//   is written.
 //
 // Until 2026-09-17 this function demanded the literal `git reset --hard
 // origin/production`, which is the FIRST half's opposite. The packaged template
@@ -206,13 +211,26 @@ function shellWord(raw) {
   return unquote(raw.replace(/[;&|)]+$/, ''));
 }
 
+// A comment neither VIOLATES nor PERMITS — the symmetry R8 already keeps for a
+// tenant literal, applied to every command this rule reads. Until d.707d only
+// half of it held: a commented-out guard was accepted (d.707c closed that),
+// while a commented-out `git pull`, `git merge` or `git reset --hard` was still
+// reported as the deploy doing it. Both halves are the same sentence — a line
+// that opens with `#` does not run — so both take the same predicate, with
+// YAML's marker rather than JavaScript's.
+//
+// The asymmetry was not merely untidy: a repository whose only `git reset
+// --hard` sat in a comment was told it resets to an unverified commit, while
+// the thing actually wrong with it — that nothing forces the tree to the
+// measured commit at all — was never said. A gate has to name what it found
+// (`.claude/rules/automation-gates.md` §1 requirement 4).
 function checkDeploySequence(ci, add) {
-  if (GIT_PULL.test(ci)) {
+  if (matchesOnExecutingLine(ci, GIT_PULL, YAML_COMMENT_OPENERS)) {
     add('R2', "'git pull' in the deploy path.\n"
       + '       A local modification on the server turns the merge into a conflict and aborts the deploy halfway.\n'
       + DEPLOY_SEQUENCE_FIX);
   }
-  if (GIT_MERGE.test(ci)) {
+  if (matchesOnExecutingLine(ci, GIT_MERGE, YAML_COMMENT_OPENERS)) {
     add('R2', "'git merge' in the deploy path.\n"
       + '       A deploy that merges builds a commit that exists on no branch, so what the box runs\n'
       + '       is no longer any commit a pipeline measured.\n'
@@ -220,7 +238,8 @@ function checkDeploySequence(ci, add) {
   }
 
   const resets = [...ci.matchAll(RESET_HARD)]
-    .map((match) => ({ at: match.index, target: shellWord(match[1]) }));
+    .map((match) => ({ at: match.index, target: shellWord(match[1]) }))
+    .filter((reset) => !isCommentLine(lineAt(ci, reset.at), YAML_COMMENT_OPENERS));
 
   if (resets.length === 0) {
     add('R2', "No 'git reset --hard' found in .gitlab-ci.yml.\n"
@@ -230,14 +249,39 @@ function checkDeploySequence(ci, add) {
     return;
   }
 
-  // Ordering is read over the whole file rather than per job: which YAML key a
-  // line sits under is the service's own half of the pipeline, and a gate that
-  // parsed jobs would be judging that half too. What it does measure is the
-  // thing that can go wrong — a guard that names another commit, another branch,
-  // or runs after the reset it is supposed to protect.
+  // A guard counts for a reset when it is in the SAME JOB and earlier in it.
+  //
+  // The job is the unit because the job is the shell: GitLab runs each job in
+  // its own container on its own runner, concatenating before_script and script
+  // into one script, and nothing a neighbouring job ran is in scope when this
+  // one resets. Until d.707 ordering was read over the whole file, which made
+  // the verdict a fact about the ORDER OF UNRELATED JOBS — a guard in a `test`
+  // job written above the deploy, or in a job whose `rules:` never fire, covered
+  // a reset that ran unguarded. Same input, different result depending on where
+  // in the file somebody put an unrelated job, which is the predictability
+  // `.claude/rules/automation-gates.md` §1 requirement 1 asks for, and a gate
+  // green over a box that resets unverified is the silence its §5 calls a defect.
+  //
+  // What is deliberately NOT resolved here is `extends:` and `!reference`: a
+  // guard pulled in from a hidden key is invisible to this reading and reported
+  // as being elsewhere. That direction is the safe one — it names a fix that
+  // makes the sequence readable in the job that runs it — and no biz repository
+  // writes the guard that way (measured over all eight, 2026-09-20).
+  //
+  // A guard has to be a line that RUNS — the permit half of the symmetry stated
+  // above this function. `# - if ! git merge-base …` left over a reset used to
+  // cover it, so a repository could comment the check out and keep the gate
+  // green; a rule a mention satisfies checks nothing (`automation-gates.md` §5).
   const guards = [...ci.matchAll(ANCESTOR_CHECK)]
     .map((match) => ({ at: match.index, commit: shellWord(match[1]), branch: shellWord(match[2]) }))
-    .filter((guard) => guard.branch === PRODUCTION_BRANCH);
+    .filter((guard) => guard.branch === PRODUCTION_BRANCH)
+    .filter((guard) => !isCommentLine(lineAt(ci, guard.at), YAML_COMMENT_OPENERS));
+
+  // Which JOB a line is in: the one reading of that question this package has
+  // (`src/utils/yamlTopLevel.js`), taken here in its widest form — a reset or a
+  // guard written under a hidden key is placed under that key rather than under
+  // whichever job happens to precede it.
+  const jobKeys = topLevelKeys(ci);
 
   for (const reset of resets) {
     if (reset.target === PRODUCTION_BRANCH) {
@@ -248,15 +292,34 @@ function checkDeploySequence(ci, add) {
         + DEPLOY_SEQUENCE_FIX);
       continue;
     }
-    if (!guards.some((guard) => guard.at < reset.at && guard.commit === reset.target)) {
-      add('R2', `The deploy resets to ${reset.target}, which is not verified to be an ancestor of `
-        + `${PRODUCTION_BRANCH} first.\n`
-        + '       A commit that is not on the branch this box follows belongs to a different history,\n'
-        + '       and resetting to it puts the box on code production never took.\n'
-        + `       Expected: git merge-base --is-ancestor ${reset.target} ${PRODUCTION_BRANCH}, on a line\n`
-        + '       BEFORE the reset, naming that same commit.\n'
+
+    const resetJob = topLevelKeyAt(jobKeys, reset.at);
+    const named = guards.filter((guard) => guard.commit === reset.target);
+
+    if (named.some((guard) => guard.at < reset.at && topLevelKeyAt(jobKeys, guard.at) === resetJob)) continue;
+
+    const elsewhere = named.find((guard) => topLevelKeyAt(jobKeys, guard.at) !== resetJob);
+    if (elsewhere) {
+      add('R2', `The ancestor check for ${reset.target} is in job "${topLevelKeyAt(jobKeys, elsewhere.at)}", `
+        + `but the reset runs in job "${resetJob}".\n`
+        + '       Every job is its own shell on its own runner, so a guard in another job never ran\n'
+        + '       when this reset does: the box resets to a commit nothing verified, and whether the\n'
+        + '       guard is there at all is decided by that other job\'s rules, not by this one.\n'
+        + `       Expected: git merge-base --is-ancestor ${reset.target} ${PRODUCTION_BRANCH} inside\n`
+        + `       job "${resetJob}", on a line BEFORE the reset — its before_script counts, GitLab\n`
+        + '       runs it as the same shell.\n'
+        + `       Fix: move the guard into job "${resetJob}", on the line before the reset.\n`
         + DEPLOY_SEQUENCE_FIX);
+      continue;
     }
+
+    add('R2', `The deploy resets to ${reset.target}, which is not verified to be an ancestor of `
+      + `${PRODUCTION_BRANCH} first.\n`
+      + '       A commit that is not on the branch this box follows belongs to a different history,\n'
+      + '       and resetting to it puts the box on code production never took.\n'
+      + `       Expected: git merge-base --is-ancestor ${reset.target} ${PRODUCTION_BRANCH}, on a line\n`
+      + `       BEFORE the reset, in job "${resetJob}", naming that same commit.\n`
+      + DEPLOY_SEQUENCE_FIX);
   }
 }
 
@@ -472,6 +535,9 @@ const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'coverage', 'dist',
 /** A call to either library helper: the own namespace, or the foreign one. */
 const NAMESPACE_HELPER_CALL = /\bget(?:Foreign)?TestNamespace\s*\(/;
 
+/** `require('./testNamespace')`, `require('../helpers/test-namespace')` — the repo's own module. */
+const REQUIRE_NAMESPACE_MODULE = /require\([^)]*test-?namespace[^)]*\)/i;
+
 /** True for the repo's shared test-namespace module, whatever it is named. */
 function isNamespaceModule(relativePath) {
   return /(^|\/)(test-?namespace)[^/]*\.js$/i.test(relativePath);
@@ -498,15 +564,41 @@ function callsNamespaceHelper(text) {
     .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));
+/** True when `pattern` matches on a line that executes, not one that describes.
+ *  `openers` says which marker opens a comment in THIS text; the rule is the
+ *  same one either way. */
+function matchesOnExecutingLine(text, pattern, openers = JS_COMMENT_OPENERS) {
+  return text.split('\n').some((line) => !isCommentLine(line, openers) && pattern.test(line));
 }
 
-/** A literal inside a comment is prose — it cannot reach a database. */
-function isCommentLine(line) {
+/**
+ * What opens a comment, per language. ONE list rather than one predicate each:
+ * the RULE is "a line that opens with a comment marker describes, it does not
+ * execute", and only the marker differs between the files this module reads
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * `#` is deliberately NOT in the JavaScript list: a private class field
+ * (`#tenantId = 100`) opens with it and very much executes, so adding it there
+ * would quietly excuse R8's own subject.
+ */
+const JS_COMMENT_OPENERS = Object.freeze(['//', '*', '/*']);
+
+/** YAML's marker — and, inside a `script:` block, the shell's. Same character. */
+const YAML_COMMENT_OPENERS = Object.freeze(['#']);
+
+/** A literal inside a comment is prose — it cannot reach a database, and a
+ *  command inside one cannot run. */
+function isCommentLine(line, openers = JS_COMMENT_OPENERS) {
   const trimmed = line.trim();
-  return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+  return openers.some((opener) => trimmed.startsWith(opener));
+}
+
+/** The whole line the offset sits on — what turns a match position into
+ *  something `isCommentLine` can judge. */
+function lineAt(text, offset) {
+  const start = text.lastIndexOf('\n', offset) + 1;
+  const end = text.indexOf('\n', offset);
+  return text.slice(start, end === -1 ? text.length : end);
 }
 
 /**
@@ -671,8 +763,26 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
     if (!/tenant_id|workspace_id/i.test(text)) continue;
     // Either the shared helper from conn-orch-validator, or a repo-local module
     // that itself reads the platform env (checked above).
+    //
+    // BOTH are earned on a line that EXECUTES. The require half was measured
+    // over the whole text until d.782b — the only one of the four permits that
+    // was — so `// TODO: require('./testNamespace')` in a comment excused a file
+    // from R8 entirely, which is the defect the helper permit had before d.700:
+    // a rule a mention satisfies checks nothing (`automation-gates.md` §5).
+    // Unifying cost nobody anything, and that was measured before it landed:
+    // of the 161 files R8 judges across `api_biz/*/tests/integration/**`, 54
+    // pass on this permit alone and all 54 carry the require on an executing
+    // line — the gate arrived with compliance, not with a backlog (§3).
+    //
+    // What deliberately stays looser: this half reads the require, not a use of
+    // what it returns, so a file that imports the module and then ignores it
+    // still passes. That is a choice, not an oversight — the module itself is
+    // the thing being trusted (it reads the platform env, and `isNamespaceModule`
+    // above holds it to that), so importing it is the statement R8 is after.
+    // Tightening it to "and then uses it" is its own decision, with its own
+    // measurement.
     if (callsNamespaceHelper(text)) continue;
-    if (/require\([^)]*test-?namespace[^)]*\)/i.test(text)) continue;
+    if (matchesOnExecutingLine(text, REQUIRE_NAMESPACE_MODULE)) continue;
 
     // Third permit — the file builds its throwaway through the library.
     //
@@ -722,18 +832,33 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
         + '       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'
+        + '       shared namespace after all, take it from one of the two sources R8\n'
+        + '       accepts: a getTestNamespace() / getForeignTestNamespace() call on an\n'
+        + '       executing line, or a require() of the repo\'s\n'
+        + '       tests/integration/testNamespace.js.\n'
         + '       Rule: api/docs/standards/tenant-allocation.md § Enforcement');
       continue;
     }
 
+    // The Expected line names BOTH sources the permits above accept, in the
+    // shape each one is actually read: `callsNamespaceHelper()` wants the call
+    // on a line that executes, the require permit wants a require() whose path
+    // names the module. Until d.778 the Fix named only the second, so a test
+    // that already used the first and failed for another reason was sent to fix
+    // a file that was not the problem (measured by BIZ-invoicing over their MR
+    // pipeline). A gate says what it checked, what it expected and what fixes
+    // it (`automation-gates.md` §1 requirement 4).
     add('R8', `${file.relative} names a tenant / workspace without taking it from the\n`
-      + '       shared test-namespace module.\n'
+      + '       namespace source this rule reads.\n'
       + '       An integration test writes into a real database, so the namespace it\n'
       + '       targets is a safety boundary — and a boundary rewritten per file is a\n'
       + '       boundary that drifts onto a live tenant.\n'
-      + '       Fix: require the repo\'s tests/integration/testNamespace.js and use it.');
+      + '       Expected: one of the TWO sources this rule accepts — a call to\n'
+      + '       getTestNamespace() or getForeignTestNamespace() on a line that executes,\n'
+      + '       or a require() whose path names the repo\'s\n'
+      + '       tests/integration/testNamespace.js.\n'
+      + '       Fix: add whichever this test needs; a helper named only in a comment or\n'
+      + '       inside a string earns neither.');
   }
 }
 

package/src/utils/envContract.js

@@ -52,7 +52,7 @@
  *   - environment read inside an installed library (`node_modules`), e.g.
  *     `SECRETS_MASTER_KEY` in @onlineapps/service-wrapper. Those names are
  *     declared by hand until libraries export their own env schemas (variant D
- *     of the F16 design, api/shared/TODO.md §5);
+ *     of the F16 design — tracked in api/shared/TODO.md under F16);
  *   - anything outside `src/`, `index.js`, `scripts/` and `config/service/*.json`.
  *
  * The scan therefore proves one direction only: what it CAN see is declared.
@@ -463,7 +463,7 @@ function verifyEnvCompleteness({ serviceRoot, contract }) {
  *
  * Runs in Tier-1 phase 0.2, before the wrapper opens a connector — a missing
  * key must fail where its name is known, not several layers deeper (defect D2:
- * SECRETS_MASTER_KEY failed in ServiceWrapper.js:916, after MQ registration).
+ * SECRETS_MASTER_KEY failed in `ServiceWrapper._initializeSecrets()`, after MQ registration).
  *
  * @param {object} args
  * @param {object|null} args.declaration normalized env declaration, null when absent

package/src/utils/handlerRef.js

@@ -22,7 +22,7 @@
  *
  *   - `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
+ *     shape check in this package goes through `parseHandlerRef` instead of
  *     restating it.
  *   - `resolveHandlerModule` states RESOLUTION: containment inside
  *     `<serviceRoot>/src`, `require`, and an export that is a function. It does
@@ -35,16 +35,14 @@
  *
  * @see api/docs/biz/10-invocation/handler-dispatch.md § `HandlerRegistry` — resolution rules
  * @see api/docs/biz/30-operations/schema-v3.md § handler
+ *
+ * The value `HANDLER_REF_REGEX` has one owner: the public entry of
+ * `@onlineapps/service-validator-core` (the mirror of the registry's rules).
+ * This module reads it from there and keeps no copy of its own.
  */
 
 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_]*$/;
+const { HANDLER_REF_REGEX } = require('@onlineapps/service-validator-core');
 
 /** How the ref is printed back to whoever has to fix it. */
 function printRef(value) {
@@ -97,7 +95,7 @@ function splitHandlerRef(handlerRef) {
 function parseHandlerRef(handlerRef) {
   const parts = splitHandlerRef(handlerRef);
 
-  if (!HANDLER_REF_PATTERN.test(handlerRef)) {
+  if (!HANDLER_REF_REGEX.test(handlerRef)) {
     throw new Error(
       '[HandlerRef] handlerRef does not match the declared form - Expected '
       + '"handlers/<path>#<exportName>" (path relative to src/, no file extension). '
@@ -178,4 +176,4 @@ function resolveHandlerModule({ serviceRoot, handlerRef } = {}) {
   return { modulePath, exportName, handler };
 }
 
-module.exports = { HANDLER_REF_PATTERN, parseHandlerRef, resolveHandlerModule };
+module.exports = { parseHandlerRef, resolveHandlerModule };

package/src/utils/integrationRun.js

@@ -183,7 +183,7 @@ function assertExistingPath(value, name, 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
+ * is executed (api/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.