@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/src/utils/stepFailure.js

@@ -15,7 +15,27 @@
  * `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).
+ *
+ * `results.steps` holds TWO kinds of record and they are not both steps. A step
+ * result is one; the entry `CookbookTestRunner.runCookbooks` pushes for a file
+ * the format check rejected is the other — a whole cookbook that produced no
+ * step at all. Each says which it is in `kind`, written where the record is
+ * made, so nothing here infers it from a missing field
+ * (`.claude/rules/architecture-principles.md` §8, Explicit Over Implicit).
+ * Until d.516b the two were conflated, and a rejected file was reported as
+ * `cookbook "broken.json" step "step #1": …` — a step that does not exist, in
+ * the one line whose job is to find the case.
+ */
+
+/** A record that IS a cookbook step: a `step_id` names it, and one must. */
+const KIND_STEP = 'step';
+
+/**
+ * A record standing for a whole cookbook that never produced a step — the file
+ * could not be loaded, or the format check rejected it. It carries no
+ * `step_id`, because it is no step.
  */
+const KIND_COOKBOOK_LOAD_FAILURE = 'cookbook-load-failure';
 
 /**
  * Which step this is — for a log line, an error list, anything a human reads.
@@ -26,29 +46,51 @@
  * every conforming cookbook logged `Step undefined: FAILED …` — measured in the
  * live biz-converter log on 2026-08-29 against a cookbook that is correct.
  *
- * The position is the last resort and it is a real answer: `step #3 (operation:
- * convert)` finds the step in the file, which `undefined` never did. A reader
- * who cannot tell which step failed has the same problem as one who was told
- * nothing (automation-gates.md §5).
+ * **A step without `step_id` is a defect, not a step to be labelled some other
+ * way.** Until d.516b this fell back to the position, `step #3 (operation:
+ * convert)`, which was the right answer while the shape was still settling: the
+ * alternative on the day was `undefined`. It is the wrong answer now. Since
+ * `@onlineapps/cookbook-core` 5.0.0 the schema requires `step_id` on every task
+ * step (`schemas/cookbook.v2.schema.json` definitions.TaskStep.required lists
+ * step_id, type, service, operation), `readCookbookSteps` refuses a step
+ * spelling it `id`, `CookbookTestRunner.validateCookbook` refuses a cookbook
+ * whose step omits it, and the orchestrator will not run a task step that fails
+ * to name its operation either (`@onlineapps/conn-orch-orchestrator`
+ * § _requireStepOperation, d.460). So the only step that can still arrive here
+ * without one is a broken step, and inventing a name for it is the silent
+ * substitution `.claude/rules/architecture-principles.md` §3 forbids — it makes
+ * the diagnostics read as if the cookbook were fine.
+ *
+ * This is about STEPS. A cookbook that produced none is a different record and
+ * is never handed to this function (`describeStepFailureWithContext` below).
+ *
+ * The position is still in the message, because it is what finds the offending
+ * step in the file; it is now part of saying WHAT IS WRONG rather than a name
+ * standing in for one (§5, `[Context] Problem - Expected/Fix`).
  *
  * @param {Object} step - a cookbook step, or a step result carrying the same keys
  * @param {number} index - zero-based position within the cookbook
- * @returns {string} never empty, never "undefined"
+ * @returns {string} the step's own `step_id`; never empty, never "undefined"
+ * @throws {Error} when the step names no `step_id`
  */
 function describeStepIdentity(step, index) {
   if (!step || typeof step !== 'object') {
     throw new Error('[stepFailure] step is required - Expected the cookbook step (or its result) to name in a message');
   }
 
-  // `step_id` only. `normalizeCookbookSteps` refuses a step spelling it `id`,
-  // so a step reaching here can no longer carry the retired name.
+  // `step_id` only. `readCookbookSteps` refuses a step spelling it `id`, so a
+  // step reaching here can no longer carry the retired name.
   if (typeof step.step_id === 'string' && step.step_id.length > 0) return step.step_id;
 
   const position = Number.isInteger(index) && index >= 0 ? index + 1 : 1;
   const operation = typeof step.operation === 'string' && step.operation.length > 0
     ? ` (operation: ${step.operation})`
     : '';
-  return `step #${position}${operation}`;
+  throw new Error(`[stepFailure] Step #${position}${operation} has no step_id - every step of a v2.1 `
+    + 'cookbook is addressed by its own step_id, so there is no name to report this step under '
+    + '(@onlineapps/cookbook-core schemas/cookbook.v2.schema.json definitions.TaskStep.required). '
+    + `Fix: add "step_id" to step #${position} of the cookbook `
+    + '(api/docs/biz/40-cookbooks/format.md § Required fields).');
 }
 
 /**
@@ -89,21 +131,66 @@ function describeStepFailure(stepResult) {
 }
 
 /**
- * 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`.
+ * How a failed record is NAMED, by what it is.
+ *
+ * `results.steps` carries two kinds and only one of them is a step (d.516b), so
+ * the name of a record is a decision about its `kind` — and one decision has one
+ * owner. Until d.523 it was made here for the orchestrator's error list and
+ * again, differently, in `utils/preValidation.js` for the CLI's, where the
+ * second copy did not make it at all: `src/cli/biz-ci-gate.js` printed
+ * `step_id` for both kinds, so a rejected cookbook reached the operator as
+ * `undefined` — the very shape d.516b removed from the other channel
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {Object} record a step result, or a cookbook-load failure
+ * @returns {string} `cookbook "<file>"` or `step "<step_id>"`
+ */
+function describeRecordIdentity(record) {
+  if (!record || typeof record !== 'object') {
+    throw new Error('[stepFailure] record is required - Expected a failed entry of results.steps to name '
+      + 'in a message. Fix: pass the record, not its reason.');
+  }
+
+  if (record.kind === KIND_COOKBOOK_LOAD_FAILURE) {
+    return `cookbook "${record.cookbook || 'unknown cookbook'}"`;
+  }
+
+  return `step "${describeStepIdentity(record, record.stepIndex)}"`;
+}
+
+/**
+ * The same reason, prefixed with enough context to find the case. WHICH context
+ * depends on what the record is, and the record says so in `kind`:
  *
- * @param {Object} stepResult - a step result carrying `cookbook`
+ *   - a cookbook that never produced a step is named by the FILE and nothing
+ *     else. There is no step in it, so there is no step to name;
+ *   - a step failure is named by cookbook, step and operation, as before.
+ *
+ * This is what step 4 puts into `results.errors`.
+ *
+ * @param {Object} record - a step result, or a cookbook-load failure, carrying
+ *   `cookbook` and its own `kind`
  * @returns {string}
  */
-function describeStepFailureWithContext(stepResult) {
-  const reason = describeStepFailure(stepResult);
-  const cookbook = stepResult.cookbook || 'unknown cookbook';
+function describeStepFailureWithContext(record) {
+  const reason = describeStepFailure(record);
+  const cookbook = record.cookbook || 'unknown cookbook';
+
+  if (record.kind === KIND_COOKBOOK_LOAD_FAILURE) {
+    return `${describeRecordIdentity(record)} could not be run: ${reason}`;
+  }
+
   // One owner for "which step": `unnamed step` used to be the answer for every
   // conforming cookbook, because the result carried neither identifier.
-  const stepId = describeStepIdentity(stepResult, stepResult.stepIndex);
-  const operation = stepResult.operation ? ` (${stepResult.operation})` : '';
-  return `cookbook "${cookbook}" step "${stepId}"${operation}: ${reason}`;
+  const operation = record.operation ? ` (${record.operation})` : '';
+  return `cookbook "${cookbook}" ${describeRecordIdentity(record)}${operation}: ${reason}`;
 }
 
-module.exports = { describeStepIdentity, describeStepFailure, describeStepFailureWithContext };
+module.exports = {
+  describeStepIdentity,
+  describeRecordIdentity,
+  describeStepFailure,
+  describeStepFailureWithContext,
+  KIND_STEP,
+  KIND_COOKBOOK_LOAD_FAILURE
+};

package/src/utils/stepReferences.js

@@ -0,0 +1,278 @@
+'use strict';
+
+const { resolveReferencesWith, resolveReferencePath } = require('@onlineapps/cookbook-core');
+
+/**
+ * The run context a Tier-1 cookbook resolves its `{{…}}` references against.
+ *
+ * WHY IT EXISTS. Until 2026-09-17 the runner executed every step independently:
+ * `stepResults` only counted, and nothing a step returned could reach the next
+ * one. A recipe therefore could not build the data it needs, so biz-converter's
+ * boot recipe depended on a row only a TEST_ONLY seed supplies — and on
+ * production Tier-1 answered `NOT_CONVERTIBLE`, the boot exited 1 after ~18
+ * minutes of backoff and the container restarted in a loop (measured
+ * 2026-09-16). The owner's decision was that the recipe stays as written and the
+ * RUNNER learns what the orchestrator already does
+ * (`api/docs/governance/confirmations/converter-boot-cookbook.md` 001).
+ *
+ * ONE RAIL, AND IT IS NOT THIS PACKAGE'S. The syntax, the type rule for a whole
+ * expression, the ban on addressing a step by position and the fate of an
+ * unresolved reference all belong to the cookbook format —
+ * `api/docs/biz/40-cookbooks/variable-references.md`. The traversal of the value
+ * and the walk of one path belong to `@onlineapps/cookbook-core`:
+ * `resolveReferencesWith()` and `resolveReferencePath()`, the same two functions
+ * `WorkflowOrchestrator._resolveInputReferencesAsync` /
+ * `_resolveTemplateExpression` call. This module writes no parser; it supplies
+ * the SCOPE, which is the only part Tier-1 owns.
+ *
+ * THE SCOPE IS THE ORCHESTRATOR'S, SPELLED THE SAME WAY. A completed entry is
+ * "the step definition unchanged, plus two added fields: `output` and
+ * `_execution`" — the section "Runtime context (`context.steps`)" of
+ * api/docs/biz/40-cookbooks/format.md — and a reference addresses it by
+ * `step_id`, which is what
+ * `WorkflowOrchestrator.referenceScope()` puts under the root `steps` (its
+ * `steps_by_id` map). A second spelling here, such as a bare `status` beside
+ * `output`, would resolve at boot and stay literal in production: precisely the
+ * divergence class that broke the converter's boot.
+ *
+ * WHAT TIER-1 DELIBERATELY DOES NOT CARRY. The orchestrator's context also holds
+ * `api_input`, `delivery` and the tenancy keys. A Tier-1 run has no workflow
+ * input and no delivery at all, so those roots are absent and a reference to
+ * them stays literal — the norm's documented outcome for an unresolvable
+ * reference, not a silent substitution.
+ *
+ * @see api/docs/biz/40-cookbooks/variable-references.md
+ * @see api/docs/biz/40-cookbooks/format.md
+ * @module utils/stepReferences
+ */
+
+/**
+ * The context one cookbook run starts from: no step has produced anything yet.
+ *
+ * It is per COOKBOOK, never per runner — `runCookbooks()` executes many
+ * cookbooks through one runner and a step of one must not see a step of
+ * another.
+ *
+ * @returns {{steps: Object}} the scope `resolveStepInput` resolves against
+ */
+function createRunContext() {
+  return { steps: {} };
+}
+
+/**
+ * Resolve the `{{…}}` references in ONE step's input.
+ *
+ * `input` is the only field expanded. The format names three expansion sites —
+ * `step.input`, a `foreach` iterator and a `switch` expression
+ * (`variable-references.md` § Limitations) — and a Tier-1 cookbook has only the
+ * first: `CookbookTestRunner.validateCookbook` requires `service` and
+ * `operation` of every step, so a `foreach` or `switch` step never reaches this
+ * runner. `expect` is not on that list and is therefore taken literally, the
+ * same as `service`, `operation` and `depends_on`.
+ *
+ * @param {Object} step - the cookbook step as written
+ * @param {{steps: Object}} runContext - what earlier steps produced
+ * @returns {Promise<*>} the input the handler is called with
+ */
+function resolveStepInput(step, runContext) {
+  return resolveReferencesWith(
+    step.input,
+    (expression) => resolveReferencePath(expression, runContext)
+  );
+}
+
+/**
+ * WHAT A TIER-1 RECIPE MAY WRITE IN `input`, checked before the run starts.
+ *
+ * Tier-1 is the service's own startup proof, so a recipe it passes must be a
+ * recipe production would accept. Two shapes broke that symmetry, both by going
+ * QUIET where production is loud:
+ *
+ *   1. a helper call — `{{webalizeString(…)}}`, `{{string2file(…)}}`. The
+ *      orchestrator resolves it through its helper registry and throws on a
+ *      name the registry does not carry
+ *      (`WorkflowOrchestrator._executeTemplateHelper`). This runner has no
+ *      registry — deliberately: a helper reaches its own runtime (ContentResolver,
+ *      files, storage), which is not what a boot probe may do. So the expression
+ *      resolved to nothing and survived as literal text, and the step ran with
+ *      `{{webalizeString(…)}}` where a value belonged.
+ *   2. a `{{steps.<id>}}` naming a step the recipe does not define. Production
+ *      refuses such a cookbook at submission with 400 `Invalid cookbook
+ *      references` (`infra/api_gateway/shared/cookbookReferences.js`,
+ *      `api/docs/governance/confirmations/cookbook-validation-placement.md` 001
+ *      — the receiver's own throw is the safety net for the paths that bypass
+ *      the gateway, and a Tier-1 boot run is exactly such a path). Here it was a
+ *      literal too.
+ *
+ * The literal outcome is right for a reference whose VALUE is missing at that
+ * moment — a step that has not run, or one that failed
+ * (`variable-references.md` § Unresolved references), and those two stay literal
+ * below. It is wrong for a name that does not exist in the recipe at all: no
+ * run can ever make it resolve.
+ *
+ * NO SECOND WALK. The traversal and the expression extraction are the same
+ * `resolveReferencesWith()` that resolves the input for real one moment later,
+ * so this check sees exactly the expressions the resolver will see. The
+ * evaluator returns `undefined` for everything: nothing is substituted here,
+ * only read.
+ *
+ * WHERE THE HELPER-CALL SHAPE OUGHT TO LIVE. `@onlineapps/cookbook-core` owns
+ * the format and exports the traversal and the path walk, but no definition of
+ * "this expression is a helper call" — the only one on the platform is the
+ * private regex in `WorkflowOrchestrator._resolveTemplateExpression`, and this
+ * module now holds a second copy of it. That is one concern on two rails
+ * (`.claude/rules/change-discipline.md` § One rail per concern) and it belongs
+ * beside `resolveReferencePath()` in cookbook-core, where both callers could
+ * read it. Recorded for the owner rather than fixed here: cookbook-core is
+ * another package's manifest.
+ *
+ * SCOPE. `input` only, which is the single expansion site a Tier-1 cookbook has
+ * (`resolveStepInput` above says why), plus `depends_on`, whose values are step
+ * names by definition.
+ *
+ * @see api/docs/biz/40-cookbooks/variable-references.md
+ * @see api/docs/governance/confirmations/cookbook-validation-placement.md
+ */
+
+/** `helperName(...)` — the shape `WorkflowOrchestrator` routes to its registry. */
+const HELPER_CALL = /^([a-zA-Z_][a-zA-Z0-9_]*)\(([\s\S]*)\)$/;
+
+/** Root of the step namespace; the only root whose names a recipe can be checked against. */
+const STEPS_ROOT = 'steps';
+
+function helperCallProblem(stepId, helperName, expression) {
+  return `Step ${stepId} input calls the template helper "${helperName}" - `
+    + `Tier-1 runs no helper registry, so "{{${expression}}}" would reach the handler as literal `
+    + 'text while the production orchestrator evaluates it (and throws when the helper name is '
+    + 'unknown). '
+    + 'Fix: remove the helper call from the step input; a Tier-1 recipe builds its values from '
+    + 'earlier steps (api/docs/biz/40-cookbooks/variable-references.md).';
+}
+
+function undefinedStepProblem(stepId, referencedId, expression, knownIds) {
+  return `Step ${stepId} references an undefined step - "{{${expression}}}" names "${referencedId}", `
+    + 'which is not a step_id of this cookbook. '
+    + `Expected one of: ${knownIds.join(', ')}. `
+    + 'Fix: correct the step_id in the reference, or add the missing step '
+    + '(api/docs/biz/40-cookbooks/variable-references.md § Unresolved references).';
+}
+
+function undefinedDependencyProblem(stepId, dependencyId, knownIds) {
+  return `Step ${stepId} depends on an undefined step - "depends_on" names "${dependencyId}", `
+    + 'which is not a step_id of this cookbook. '
+    + `Expected one of: ${knownIds.join(', ')}. `
+    + 'Fix: correct the step_id in "depends_on", or add the missing step '
+    + '(api/docs/biz/40-cookbooks/format.md § Step definition).';
+}
+
+/**
+ * What ONE expression is, measured against the names this cookbook defines.
+ *
+ * A path whose root is not `steps` — `api_input.…`, `context.…`, `current.…` —
+ * is left alone: its value comes into being at run time and a recipe says
+ * nothing about whether it will. The BRACKET form `steps[0]` is not a step
+ * reference either, in this runner or at the gateway; the dotted `steps.0` is,
+ * and it names a step no recipe can define.
+ *
+ * @returns {string|null} the problem, or `null` when the expression is fine
+ */
+function checkExpression(expression, stepId, known, knownIds) {
+  const helperCall = expression.match(HELPER_CALL);
+  if (helperCall) {
+    return helperCallProblem(stepId, helperCall[1], expression);
+  }
+
+  const parts = expression.split('.');
+  if (parts[0] !== STEPS_ROOT || parts.length < 2) return null;
+
+  const referencedId = parts[1];
+  if (known.has(referencedId)) return null;
+
+  return undefinedStepProblem(stepId, referencedId, expression, knownIds);
+}
+
+/**
+ * The problem this cookbook's step inputs carry, or `null` when they carry none.
+ *
+ * Returns the FIRST problem rather than throwing, the way
+ * `utils/cookbookFormat.checkCookbookFormatVersion` does: the caller owns the
+ * `[Context]` of the message it throws, and the caller here is the runner
+ * (`.claude/rules/architecture-principles.md` §5).
+ *
+ * @param {Array<Object>} steps - the cookbook's steps, already proved to be the array shape
+ * @returns {Promise<string|null>} the problem text without its context prefix
+ */
+async function checkStepInputExpressions(steps) {
+  const knownIds = steps
+    .map((step) => step && step.step_id)
+    .filter((stepId) => typeof stepId === 'string' && stepId.length > 0);
+  const known = new Set(knownIds);
+
+  for (const step of steps) {
+    const dependencies = Array.isArray(step.depends_on) ? step.depends_on : [];
+    for (const dependency of dependencies) {
+      if (typeof dependency !== 'string' || known.has(dependency)) continue;
+      return undefinedDependencyProblem(step.step_id, dependency, knownIds);
+    }
+
+    let problem = null;
+    await resolveReferencesWith(step.input, (expression) => {
+      if (problem === null) {
+        problem = checkExpression(expression, step.step_id, known, knownIds);
+      }
+      return undefined;
+    });
+    if (problem !== null) return problem;
+  }
+
+  return null;
+}
+
+/**
+ * Write one finished step into the run context, under its own name.
+ *
+ * `output` appears ONLY on a step that passed — "an entry carries `output` and
+ * `_execution` once it has completed, not before"
+ * (the same "Runtime context (`context.steps`)" section). A step that failed is
+ * recorded with its status and no output, so a reference into it resolves to
+ * nothing and survives as literal text: the cookbook author sees
+ * `{{steps.x.output.id}}` sitting in the failing step's input, which names the
+ * real cause.
+ *
+ * The `step_id` is REQUIRED here rather than assumed. `validateCookbook`
+ * already refuses a cookbook whose step has none, so in a run this cannot
+ * happen; the check is at the entry of this function because the alternative is
+ * a silent `steps[undefined]` — a nameless step that a later reference could
+ * never address on purpose (architecture-principles.md §4).
+ *
+ * @param {{steps: Object}} runContext - the context to write into
+ * @param {Object} step - the cookbook step as written
+ * @param {{passed: boolean, actual: *}} result - the step's result record
+ * @returns {void}
+ */
+function recordStepOutcome(runContext, step, result) {
+  if (typeof step.step_id !== 'string' || step.step_id.length === 0) {
+    throw new Error('[stepReferences] A step with no step_id cannot enter the run context - Expected a '
+      + 'non-empty "step_id"; a step is addressed by its name and never by its position '
+      + '(api/docs/biz/40-cookbooks/variable-references.md § Rules). '
+      + 'Fix: add "step_id" to the step.');
+  }
+
+  const entry = {
+    ...step,
+    _execution: { status: result.passed ? 'completed' : 'failed' }
+  };
+
+  if (result.passed) {
+    entry.output = result.actual;
+  }
+
+  runContext.steps[step.step_id] = entry;
+}
+
+module.exports = {
+  createRunContext,
+  resolveStepInput,
+  recordStepOutcome,
+  checkStepInputExpressions
+};

package/src/utils/testCoverageContract.js

@@ -43,6 +43,23 @@
  * why the jest binary is the SERVICE's own (resolved from its `node_modules`),
  * not this package's: a different jest version resolves a different `testMatch`.
  *
+ * ## Why an empty set is a finding rather than a clean run
+ *
+ * Every comparison here iterates a set, so over an empty one it finds no
+ * counter-example — and an empty match is jest's own exit 0 with no output.
+ * A repository whose jest matched nothing therefore passed, and the gate printed
+ * `0 file(s) matched, 0 run by the test:all chain` as if that were a
+ * measurement. The same held one level down: a `test:all` step aimed at an empty
+ * directory listed 0 files, exited 0, and contributed nothing to either side of
+ * any comparison (both measured 2026-09-15, finding d.205).
+ *
+ * So an empty T, and an empty answer from any jest invocation the chain reaches,
+ * are named: a gate that reports OK over something it never observed is the
+ * false guarantee automation-gates.md §5 calls a defect of the same severity as
+ * a wrong result. Each is reported only where it is the ROOT — an empty T
+ * silences the per-step check, and so does a file on disk that the config does
+ * not match, because there every empty step is that defect's shadow.
+ *
  * ## Why a declared tier exists at all
  *
  * `tests/e2e/mq-invocation` needs a live consumer on the service workflow queue.
@@ -77,7 +94,8 @@ const { spawnSync } = require('child_process');
 
 const TEST_COVERAGE_SCOPE = 'files the service jest config matches (jest --listTests) vs. the files '
   + 'the test:all chain runs, decomposed npm run → jest, plus the scripts declared in contract stackTiers; '
-  + 'and that same matched set vs. every platform test file present on disk (**/tests/**/*.test.js)';
+  + 'and that same matched set vs. every platform test file present on disk (**/tests/**/*.test.js); '
+  + 'and that neither the matched set nor any jest invocation the test:all chain reaches is empty';
 
 const TEST_COVERAGE_NOT_MEASURED = 'whether a declared stack tier is ever RUN — the declaration says '
   + 'why it cannot run in test:all, never that something else runs it';
@@ -437,10 +455,31 @@ function verifyTestCoverage({ serviceRoot, contract, spawn = spawnSync }) {
   const relative = (absolutePath) => path.relative(serviceRoot, absolutePath);
   const violations = [];
   const add = (requirement, message) => violations.push({ requirement, message });
+  const has = (requirement) => violations.some((violation) => violation.requirement === requirement);
 
   // T — everything the service's jest config matches, asked without a path filter.
   const matched = new Set(ask([]));
 
+  // T = ∅ — the gate ran and measured nothing.
+  //
+  // An empty match is jest's own exit 0 with no output (§ listTests), so nothing
+  // in the run distinguishes it from a healthy one. And every comparison below
+  // iterates a set: over an empty T, T \ (A ∪ B) and D \ T find no
+  // counter-example for the same reason an empty sum is zero. The gate printed
+  // "OK test-coverage — 0 file(s) matched, 0 run by the test:all chain" and the
+  // reader took it for a measurement (measured 2026-09-15, finding d.205).
+  //
+  // Reported here and nowhere else: when the config matches nothing, every step
+  // of the chain lists nothing too, and one defect with one fix must not arrive
+  // as one violation per step.
+  if (matched.size === 0) {
+    add('TEST_SET_EMPTY', 'Nothing measured - the service jest config matches 0 test files, '
+      + 'so "jest --listTests" (the service\'s own jest, no path filter) returns an empty set, every '
+      + 'comparison this gate makes is vacuously satisfied, and the run prints OK over a service whose '
+      + `coverage was never observed. Fix: widen testMatch in jest.config.js to the platform pattern `
+      + `(${PLATFORM_TEST_FILE_PATTERN}), or add the test files the service is missing.`);
+  }
+
   // D \ T — a suite that is on disk and in no jest answer. Checked FIRST because
   // it is the only defect the other three cannot express: a file jest does not
   // match is missing from both sides of every comparison below, so silence there
@@ -459,7 +498,26 @@ function verifyTestCoverage({ serviceRoot, contract, spawn = spawnSync }) {
   for (const problem of chain.problems) add('TEST_ALL_CHAIN', problem.message);
   const inTestAll = new Set();
   for (const command of chain.commands) {
-    for (const file of ask(command.args)) inTestAll.add(file);
+    const files = ask(command.args);
+
+    // A step that lists nothing runs nothing — and says so with exit 0, so the
+    // script stays green in every pipeline while measuring nothing. It is what a
+    // narrowed pattern, a renamed directory or a moved suite leaves behind, and
+    // it is invisible to every other check here: a step contributing no file
+    // changes neither side of any comparison.
+    // Only where the matched set is the whole truth: T non-empty (checked above)
+    // and nothing on disk left outside it. A config that misses files on disk is
+    // already named, and every step aimed at those files lists 0 as a CONSEQUENCE
+    // of it — reporting the shadow beside the thing casting it buries the fix.
+    if (matched.size > 0 && !has('TEST_NOT_MATCHED') && files.length === 0) {
+      const invocation = ['jest', ...command.args].join(' ').trim();
+      add('TEST_SET_EMPTY', `Chain step runs no test - "${CHAIN_ENTRY_SCRIPT}" reaches `
+        + `"${invocation}" (via ${command.viaScript}), and jest lists 0 files for it, so the step exits 0 `
+        + `having measured nothing. Fix: point "${command.viaScript}" at the tests it is meant to run, `
+        + `or remove the step from the ${CHAIN_ENTRY_SCRIPT} chain.`);
+    }
+
+    for (const file of files) inTestAll.add(file);
   }
 
   // B — everything the declared stack tiers run.