@onlineapps/conn-orch-validator 10.0.0 → 12.0.0

package/src/utils/envReads.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Which environment names a service's image reads — asked by a deploy gate,
+ * answered by the contract (d.533c).
+ *
+ * ## The defect this ends
+ *
+ * `api/scripts/validate-env.sh` refuses a deploy when a key in the target's
+ * `.env` still says `CHANGE_ME`. Pointed at a biz service it refused on
+ * `JWT_SECRET`, a key the gateway reads and no biz image ever opens: the gate
+ * was judging the platform's whole key set against one service. The fix is not
+ * a list of exceptions in bash — it is the service saying what it reads.
+ *
+ * ## Why not a grep for `process.env`
+ *
+ * Because most of the platform's environment is read inside installed
+ * libraries: `@onlineapps/service-wrapper` reads `SECRETS_MASTER_KEYS`,
+ * `@onlineapps/conn-base-cache` reads `REDIS_URL`. A grep over `src/` sees none
+ * of them and would answer a set too small — which in a gate means a key
+ * silently unchecked. That blind spot is stated, not discovered:
+ * `utils/envContract.js` § Measurability boundary.
+ *
+ * ## The set is the uniform's, not a second definition
+ *
+ * The answer is `collectDeclaredEnvNames` — the contract's `env` block, the
+ * `${VAR}` placeholders of `config/service/*.json`, and the endpoint variables
+ * of the connectors the contract declares required. That is exactly the set row
+ * `C-ENV-READS` of the biz-service uniform measures the repository against, so
+ * the two can never disagree about what a service reads
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * The consequence is deliberate: a name the SOURCE reads and the contract does
+ * not declare is absent from this answer. It is a blocking finding of
+ * `C-ENV-READS`, with its own fix, and a gate must not demand a value for a key
+ * nobody owns.
+ *
+ * The messages carry the context `[oa-validate]` because the subcommand is this
+ * module's only caller and the message goes to a bash gate reading stderr; there
+ * is no wrapper re-wording them, which is how they stay the exact sentence the
+ * test asserts (`automation-gates.md` §2).
+ *
+ * @see api/docs/biz/70-contracts/env-contract.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadAndValidateIntegrationContract } = require('./bizCiGateContract');
+const { collectDeclaredEnvNames } = require('./envContract');
+
+/** Where every biz service declares what it integrates with. */
+const CONTRACT_RELATIVE_PATH = path.join('config', 'service', 'integration-contract.json');
+
+/**
+ * Every environment name the service at `serviceRoot` reads, as the uniform
+ * measures it.
+ *
+ * @param {string} serviceRoot repository root of the service; the caller
+ *   resolves its own default, so an empty value is refused rather than silently
+ *   answered about `process.cwd()`
+ * @returns {string[]} the names, sorted, without duplicates
+ * @throws {Error} when the root or the contract cannot be read — a gate that
+ *   cannot get the set must stop, never continue with an empty one
+ */
+function listEnvReads(serviceRoot) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.trim() === '') {
+    throw new Error('[oa-validate] No service root to answer about - --env-reads was given '
+      + `${typeof serviceRoot === 'string' ? 'an empty path' : typeof serviceRoot}. `
+      + 'Fix: oa-validate --env-reads <serviceRoot>, or run it inside the service repository.');
+  }
+
+  const root = path.resolve(serviceRoot);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`[oa-validate] Service root not found - ${root}. `
+      + 'Fix: pass an existing repository directory, or run the command inside the service repository.');
+  }
+
+  const contractPath = path.join(root, CONTRACT_RELATIVE_PATH);
+  if (!fs.existsSync(contractPath)) {
+    throw new Error(`[oa-validate] No environment contract - ${contractPath} does not exist, so nothing `
+      + 'declares which environment names this service reads and the answer would be an empty set. '
+      + 'Fix: add config/service/integration-contract.json with requiredConnectors and, where the '
+      + 'service reads a name no placeholder and no connector covers, an "env" block.');
+  }
+
+  let contract;
+  try {
+    contract = loadAndValidateIntegrationContract(root).contract;
+  } catch (error) {
+    throw new Error(`[oa-validate] Unusable environment contract - ${contractPath}: `
+      + `${String(error.message).split('\n')[0].trim()} `
+      + 'Fix: correct the contract, then run npx oa-validate to see the row that judges it.');
+  }
+
+  return collectDeclaredEnvNames({ serviceRoot: root, contract }).names;
+}
+
+module.exports = {
+  CONTRACT_RELATIVE_PATH,
+  listEnvReads
+};

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/testNamespace.js

@@ -202,6 +202,16 @@ function assertAllowedTenant(tenantId, options) {
  * fallback there would hide exactly the misconfiguration the boundary exists to
  * surface (architecture-principles.md §3).
  *
+ * What it DOES hold is the shape of a workspace id: a POSITIVE integer. The
+ * recorded decision names it (api/docs/governance/confirmations/tier1-runner-workspace.md,
+ * entry 002) and `.claude/rules/workspace-architecture.md` says `workspace_id` 0
+ * is not a value; the guard checked `Number.isInteger` only, so `0` and `-5` came
+ * back normalized and a cookbook could send the boot probe into a workspace that
+ * cannot exist. The check lives here rather than in `normalizeNamespaceId()`
+ * because the tenant rail already refuses both — by the class allowlist, for a
+ * different reason and with a different fix — and one message per boundary is
+ * what keeps the refusal actionable.
+ *
  * There is deliberately NO class allowlist here, and that is not an omission:
  *
  *   - `api/docs/standards/tenant-allocation.md` allocates environment classes to
@@ -222,7 +232,7 @@ function assertAllowedTenant(tenantId, options) {
  *        `purpose` is the name the caller knows the id by (here, the cookbook key
  *        that carries it), `setBy` where that name is given a value.
  * @returns {number} the normalized id.
- * @throws {Error} when the id is absent or not an integer.
+ * @throws {Error} when the id is absent, not an integer, or not positive.
  */
 function assertWorkspaceId(workspaceId, options) {
   if (options === null || typeof options !== 'object') {
@@ -232,7 +242,14 @@ function assertWorkspaceId(workspaceId, options) {
   requireOriginText(purpose, 'purpose');
   requireOriginText(setBy, 'setBy');
 
-  return normalizeNamespaceId(workspaceId, { purpose, setBy });
+  const value = normalizeNamespaceId(workspaceId, { purpose, setBy });
+  if (value <= 0) {
+    throw new Error(`[TestNamespace] Invalid ${purpose}=${value} - Expected a positive integer `
+      + 'workspace id (1 or greater); 0 identifies no workspace. '
+      + `Fix: set ${purpose} to the workspace the run owns - ${setBy} - `
+      + 'see api/docs/standards/tenant-allocation.md § The allocation.');
+  }
+  return value;
 }
 
 /**
@@ -275,9 +292,19 @@ function getTestNamespace() {
     setBy: ENV_SET_BY
   });
 
+  // The workspace takes the same shape check a cookbook's declared value takes,
+  // under the same function and the same sentence. It did not, and that made the
+  // boundary half a boundary: the positivity rule held for a value a cookbook
+  // declares and not for the variable every integration test and every boot
+  // probe actually runs under (measured: TESTING_WORKSPACE_ID=0 returned
+  // workspace_id 0). The tenant above shows the shape — the env is one caller of
+  // a boundary, never its owner.
   return {
     tenant_id: tenantId,
-    workspace_id: readNamespaceId('TESTING_WORKSPACE_ID')
+    workspace_id: assertWorkspaceId(readNamespaceId('TESTING_WORKSPACE_ID'), {
+      purpose: 'TESTING_WORKSPACE_ID',
+      setBy: ENV_SET_BY
+    })
   };
 }
 

package/src/validators/ServiceStructureValidator.js

@@ -906,8 +906,14 @@ class ServiceStructureValidator {
       this.errors.push({
         type: 'MISSING_COOKBOOKS',
         path: 'tests/cookbooks',
+        // The problem only. The remedy is `fix`, and the printer composes the
+        // two — `formatResult` below writes a `Fix:` line of its own, the
+        // service wrapper composes `message (Fix: fix)` inline. A message that
+        // carries `Fix:` as well prints the remedy twice, which reads as two
+        // instructions; this was the only one of the validator's findings that
+        // did it (d.599).
         message: '[ServiceStructure] tests/cookbooks is missing or empty - Tier-1 boot '
-          + 'validates operations by these recipes. Fix: add tests/cookbooks/<op>.json',
+          + 'validates operations by these recipes.',
         fix: 'add tests/cookbooks/<op>.json'
       });
       return;