@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/utils/operationsDocumentRules.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * The rules about the `config/service/operations.json` DOCUMENT — one
+ * definition, asked by every rail, so one question gets one answer.
+ *
+ * Three rules live here:
+ *
+ *   1. the document declares `schema_version: "3.0"` — the version of the
+ *      operation schema it is written in;
+ *   2. the map it wraps declares at least one operation — a dispatch table with
+ *      nothing in it is a service with no reason to boot;
+ *   3. each declaration is complete enough for a cookbook to be generated from
+ *      it — `input` and `output` (errors), `description` (a warning).
+ *
+ * ## Why these are NOT in `@onlineapps/service-validator-core`
+ *
+ * Because the Registry never sees this document. Registration sends
+ * `doc.operations` alone — the map, not the file — so `schema_version` and a
+ * sibling key of it never reach the Registry, and the Registry has no rule
+ * about either. The core package holds the MIRROR of the Registry's rules
+ * (owner decision `api/docs/governance/confirmations/operations-schema-mirror.md`
+ * 001), and its own header promises it "adds no rule and drops no rule".
+ * Putting a rule the Registry does not have into that mirror would make the
+ * promise false and the mirror unreadable as a mirror.
+ *
+ * Rule 3 is the same case seen from the other side: the Registry generates no
+ * cookbook, so it needs none of `input`, `output`, `description`; the two rails
+ * that DO generate one cannot boot a service without them.
+ *
+ * These three rules belong to the tool that reads REPOSITORIES — this package —
+ * and their home here is the owner-approved answer, not a waypoint: do not move
+ * them into the core because they look like they belong beside the per-operation
+ * rules. `src/utils/operationsRules.js` is the adapter to those; this module is
+ * the owner of these. Lead decision 2026-09-20 (batch d.465b), on the measured
+ * alternative of putting them in the core, which no rail could have called.
+ *
+ * ## What it replaced (measured 2026-09-20)
+ *
+ * An empty operations map had FOUR answers: an error
+ * (`ServiceReadinessValidator`), a warning (`ServiceStructureValidator`
+ * `NO_OPERATIONS`), silence — a clean PASS — (`ValidationOrchestrator` step 4)
+ * and a finding (the uniform row `C-OPS`). A missing `schema_version` had none:
+ * `ServiceStructureValidator` compared the value only `if` it was there.
+ * Now every rail asks this module, and the answer is an error everywhere — the
+ * stricter of the four, because a service that dispatches nothing cannot serve
+ * a single cookbook step.
+ *
+ * Layer: L3 (Orchestration). No filesystem, no environment, no dependencies.
+ *
+ * @see api/docs/biz/30-operations/schema-v3.md § File shape
+ * @see api/docs/governance/confirmations/operations-schema-mirror.md
+ */
+
+/** The one document these rules are about, named the same way in every finding. */
+const OPERATIONS_FILE = 'config/service/operations.json';
+
+/** The only operation-schema version this platform dispatches. */
+const OPERATIONS_SCHEMA_VERSION = '3.0';
+
+/** How every finding of this module says what to do about it. */
+const SET_VERSION_FIX = `set "schema_version": "${OPERATIONS_SCHEMA_VERSION}" in ${OPERATIONS_FILE}`;
+
+/** The two severities a finding of this module carries, named once. */
+const SEVERITY_ERROR = 'error';
+const SEVERITY_WARNING = 'warning';
+
+/**
+ * Whether a value is a plain object — the shape both rules presuppose.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Rule 2, on the map alone — for the rail that never holds the document.
+ *
+ * A map that is missing, null or not a plain object is NOT this rule's business:
+ * that one the Registry does have, so `utils/operationsRules.js` answers it and
+ * this module stays silent rather than giving the same defect a second voice.
+ *
+ * @param {*} operations - the `operations` map
+ * @returns {Array<{field: string, what: string, fix: string}>}
+ */
+function operationsMapFindings(operations) {
+  if (!isPlainObject(operations)) return [];
+  if (Object.keys(operations).length > 0) return [];
+
+  return [{
+    field: 'operations',
+    what: 'declares no operations — a service that dispatches nothing has no reason to boot',
+    fix: `declare at least one operation in ${OPERATIONS_FILE}`,
+    severity: SEVERITY_ERROR
+  }];
+}
+
+/**
+ * Both rules, on the parsed document — for every rail that holds the file.
+ *
+ * @param {*} document - parsed contents of `config/service/operations.json`
+ * @returns {Array<{field: string, what: string, fix: string}>}
+ */
+function operationsDocumentFindings(document) {
+  const findings = [];
+  const declared = isPlainObject(document) ? document.schema_version : undefined;
+
+  if (declared === undefined || declared === null) {
+    findings.push({
+      field: 'schema_version',
+      what: 'absent — the document does not say which operation schema it is written in, '
+        + 'so nothing can tell a v3 declaration from an older one',
+      fix: SET_VERSION_FIX,
+      severity: SEVERITY_ERROR
+    });
+  } else if (declared !== OPERATIONS_SCHEMA_VERSION) {
+    findings.push({
+      field: 'schema_version',
+      what: `is ${JSON.stringify(declared)} — this platform dispatches operation schema `
+        + `${OPERATIONS_SCHEMA_VERSION} and no other`,
+      fix: SET_VERSION_FIX,
+      severity: SEVERITY_ERROR
+    });
+  }
+
+  findings.push(...operationsMapFindings(isPlainObject(document) ? document.operations : undefined));
+  return findings;
+}
+
+/**
+ * Rule 3 — is each declaration complete enough for a cookbook to be generated
+ * from it?
+ *
+ * This is a document rule for the same reason as the other two: the Registry
+ * has none of it. It never generates a cookbook, so it never needs `input`,
+ * `output` or `description`; the two rails that DO generate one —
+ * `ValidationOrchestrator` step 4 and the readiness score — need all three.
+ *
+ * The severity is not a new decision. Both rails already answered `input` and
+ * `output` with an error and `description` with a warning, and agreed
+ * (measured d.465c); what they disagreed about was every sentence — `Operation
+ * x: missing input schema` against `Operation 'x' missing input schema`. One
+ * rule stated in two texts is still two rails, because the next edit moves one
+ * of them and nothing notices.
+ *
+ * A value that is not an object is not this rule's business: the Registry owns
+ * that one, and `utils/operationsRules.js` reports it.
+ *
+ * @param {*} operations - the `operations` map
+ * @returns {Array<{operation: string, field: string, what: string, fix: string, severity: string}>}
+ */
+function operationsDeclarationFindings(operations) {
+  if (!isPlainObject(operations)) return [];
+
+  const findings = [];
+  for (const [name, operation] of Object.entries(operations)) {
+    if (!isPlainObject(operation)) continue;
+
+    for (const field of ['input', 'output']) {
+      if (operation[field]) continue;
+      findings.push({
+        operation: name,
+        field,
+        what: `no ${field} schema — a cookbook step generated from this declaration `
+          + `has nothing to shape its ${field} by`,
+        fix: `add "${field}" (a JSON Schema object) to the operation in ${OPERATIONS_FILE}`,
+        severity: SEVERITY_ERROR
+      });
+    }
+
+    if (!operation.description) {
+      findings.push({
+        operation: name,
+        field: 'description',
+        what: 'no description — the operation catalogue and the generated cookbook step '
+          + 'have nothing to call it',
+        fix: `add "description" to the operation in ${OPERATIONS_FILE}`,
+        severity: SEVERITY_WARNING
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * The findings of one severity, in declaration order.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @param {string} severity - `SEVERITY_ERROR` or `SEVERITY_WARNING`
+ * @returns {Array<object>}
+ */
+function ofSeverity(findings, severity) {
+  return findings.filter((finding) => finding.severity === severity);
+}
+
+/**
+ * One document finding as a single sentence, for a rail that collects strings.
+ *
+ * The `Fix:` sentence is part of it: a rail reporting strings has nowhere else
+ * to carry the remedy (`architecture-principles.md` §5).
+ *
+ * @param {{field: string, what: string, fix: string}} finding
+ * @returns {string}
+ */
+function documentFindingSentence(finding) {
+  const subject = finding.operation === undefined
+    ? `${OPERATIONS_FILE} —`
+    : `${OPERATIONS_FILE} — operation '${finding.operation}',`;
+  return `${subject} ${finding.field}: ${finding.what}. Fix: ${finding.fix}.`;
+}
+
+/**
+ * One document finding as a record, for a rail that collects objects.
+ *
+ * @param {{field: string, what: string, fix: string}} finding
+ * @returns {{type: string, path: string, field: string, message: string, fix: string}}
+ */
+function documentFindingRecord(finding) {
+  return {
+    type: 'INVALID_OPERATIONS_DOCUMENT',
+    path: OPERATIONS_FILE,
+    field: finding.field,
+    message: `${OPERATIONS_FILE} — ${finding.field}: ${finding.what}`,
+    fix: finding.fix
+  };
+}
+
+module.exports = {
+  OPERATIONS_FILE,
+  OPERATIONS_SCHEMA_VERSION,
+  SEVERITY_ERROR,
+  SEVERITY_WARNING,
+  ofSeverity,
+  operationsDeclarationFindings,
+  operationsMapFindings,
+  operationsDocumentFindings,
+  documentFindingSentence,
+  documentFindingRecord
+};

package/src/utils/operationsRules.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * The per-operation rules of `config/service/operations.json`, read from the one
+ * place that owns them, and rendered in the two shapes the rails of this package
+ * report in.
+ *
+ * The rules themselves are NOT here and must never be: they are the rules the
+ * Registry applies when a service registers, and the owner decided where they
+ * live — `@onlineapps/service-validator-core`, `validateOperationsSchema`
+ * (`api/docs/governance/confirmations/operations-schema-mirror.md` 001, which
+ * rejected a copy in this package in so many words). This module is the adapter
+ * that lets a rail here ask that one question and print the answer in its own
+ * voice.
+ *
+ * What it replaced (measured 2026-09-20, d.465): three rails restated the rules
+ * from memory — `ValidationOrchestrator.validateOperations` (boot step 4),
+ * `ServiceStructureValidator.validateOperation` (boot step 1) and
+ * `ServiceReadinessValidator.checkOperationsCompliance` (the readiness score),
+ * with a fourth copy in the jest suite `createServiceReadinessTests` generates
+ * for every biz repository. All four knew `handler`, `bundle_scope` and the
+ * retired v2 fields; NONE of them knew `mutates`, `resource_type` or the
+ * kebab-case key rule, which are the three the Registry refuses a registration
+ * on. An operation violating them therefore passed every local check and
+ * surfaced as a crash loop after restart — the defect the confirmation exists to
+ * remove (`change-discipline.md` § One rail per concern).
+ *
+ * Layer: L3 (Orchestration). No filesystem, no environment.
+ *
+ * @see api/docs/governance/confirmations/operations-schema-mirror.md
+ * @see api/docs/biz/30-operations/schema-v3.md
+ */
+
+/**
+ * The owning definition, required at CALL time rather than at load time.
+ *
+ * `oa-validate` is started from a copy of this engine's `src/` tree — that is
+ * how an installed package runs, and how three acceptance suites plant one —
+ * and the engine's own guards (no `package.json`, no workspace root) speak
+ * before any row runs. A top-level `require` of a sibling package here loads
+ * before those guards get a chance, so a copy with nothing installed beside it
+ * died with `MODULE_NOT_FOUND` and a stack instead of the one actionable
+ * sentence `architecture-principles.md` §5 demands
+ * (`tests/unit/oaValidateCli.integration.test.js` § an engine copy carrying no
+ * package.json). Asking at call time keeps the dependency exactly as hard as it
+ * was — the row cannot answer without it — while leaving the order of the
+ * engine's messages intact. The package's own `index.js` defers for the same
+ * reason.
+ *
+ * @returns {Function} `validateOperationsSchema` of `@onlineapps/service-validator-core`
+ */
+function owningDefinition() {
+  return require('@onlineapps/service-validator-core').validateOperationsSchema;
+}
+
+/** The one document these rules are about, named the same way in every finding. */
+const OPERATIONS_FILE = 'config/service/operations.json';
+
+/**
+ * Split a mirror reason into the problem and the fix it already carries.
+ *
+ * Several of the Registry's reasons end in a `Fix:` sentence and the rest do
+ * not. A rail that reports `{ message, fix }` needs both halves, so the halves
+ * are taken from the reason where it has them, and composed from the field it
+ * names where it does not. Nothing is invented about the RULE either way — the
+ * sentence that states the rule is always the Registry's own.
+ *
+ * @param {string} reason - `reason` of one mirror finding
+ * @returns {{ what: string, fix: string|null }}
+ */
+function splitReason(reason) {
+  const marker = reason.indexOf('Fix:');
+  if (marker === -1) return { what: reason.trim(), fix: null };
+
+  return {
+    what: reason.slice(0, marker).replace(/\s*[-–—]\s*$/, '').trim(),
+    fix: reason.slice(marker + 'Fix:'.length).trim()
+  };
+}
+
+/**
+ * One mirror finding as a single sentence, for a rail that collects strings.
+ *
+ * @param {{operation: string, field: string, reason: string}} finding
+ * @returns {string}
+ */
+function findingSentence(finding) {
+  if (finding.operation === '(root)') {
+    return `${OPERATIONS_FILE}: ${finding.reason}`;
+  }
+  return `Operation '${finding.operation}' — ${finding.field}: ${finding.reason}`;
+}
+
+/**
+ * One mirror finding as a record, for a rail that collects objects.
+ *
+ * `type` is the Registry's own error code for the whole verdict, not a taxonomy
+ * of this package: a caller reading `INVALID_OPERATIONS_SCHEMA` here and in the
+ * rejection message is reading the same word about the same rule.
+ *
+ * @param {{operation: string, field: string, reason: string}} finding
+ * @param {string} errorCode - `errorCode` of the verdict the finding came from
+ * @returns {{type: string, path: string, operation: string, field: string, message: string, fix: string}}
+ */
+function findingRecord(finding, errorCode) {
+  const { what, fix } = splitReason(finding.reason);
+
+  return {
+    type: errorCode,
+    path: OPERATIONS_FILE,
+    operation: finding.operation,
+    field: finding.field,
+    message: `Operation "${finding.operation}" — ${finding.field}: ${what}`,
+    fix: fix === null
+      ? `Correct "${finding.field}" of operation "${finding.operation}" in ${OPERATIONS_FILE} `
+        + '— see api/docs/biz/30-operations/schema-v3.md.'
+      : fix
+  };
+}
+
+/**
+ * Ask the owning definition, and get the answer as sentences.
+ *
+ * @param {object|null|undefined} operations - the `operations` map
+ * @returns {{ valid: boolean, errorCode: string|null, sentences: string[] }}
+ */
+function operationsRuleSentences(operations) {
+  const verdict = owningDefinition()(operations);
+  return {
+    valid: verdict.valid,
+    errorCode: verdict.errorCode,
+    sentences: verdict.errors.map(findingSentence)
+  };
+}
+
+/**
+ * Ask the owning definition, and get the answer as records.
+ *
+ * @param {object|null|undefined} operations - the `operations` map
+ * @returns {{ valid: boolean, errorCode: string|null, records: object[] }}
+ */
+function operationsRuleRecords(operations) {
+  const verdict = owningDefinition()(operations);
+  return {
+    valid: verdict.valid,
+    errorCode: verdict.errorCode,
+    records: verdict.errors.map((finding) => findingRecord(finding, verdict.errorCode))
+  };
+}
+
+module.exports = {
+  OPERATIONS_FILE,
+  findingSentence,
+  findingRecord,
+  operationsRuleSentences,
+  operationsRuleRecords
+};

package/src/utils/resolveHeaders.js

@@ -26,7 +26,18 @@ function resolveHeaders(headers, options = {}) {
     const resolvedValue = valueStr.replace(/\$\{([A-Z0-9_]+)\}/g, (_match, varName) => {
       const envValue = env[varName];
       if (envValue === undefined || envValue === null || String(envValue).trim() === '') {
-        throw new Error(`[conn-orch-validator][Headers] Missing environment variable - Expected ${varName} for header ${key}`);
+        // The `Fix:` half is what `architecture-principles.md` §5 asks of every
+        // config error, in the wording
+        // `api/docs/standards/ARCHITECTURE_PRINCIPLES.md` § Config Contract
+        // Exceptions owns: a key whose schema declares no owning env file is
+        // sent to `env-active/*.env`, and a location nobody declared is never
+        // invented. A header placeholder has no schema, so that is the location
+        // it gets — plus the other way out this rail really has, a literal
+        // value in the cookbook step.
+        throw new Error(
+          `[conn-orch-validator][Headers] Missing environment variable - Expected ${varName} for header ${key}. `
+            + `Fix: set ${varName} in env-active/*.env, or replace the placeholder with a literal value in the cookbook step's headers.`
+        );
       }
       return String(envValue);
     });

package/src/utils/setupDatabase.js

@@ -5,7 +5,7 @@
  *
  * The service declares WHAT its database is in integration-contract.json; this
  * decides HOW it gets built, identically for all of them
- * (docs/biz/00-model/uniformity-principle.md).
+ * (api/docs/biz/00-model/uniformity-principle.md).
  *
  * It replaces six per-repo ci-setup-db.js scripts that had each solved the same
  * problem differently — 113, 69, 56, 54, 22 and 20 lines, in three strategies,

package/src/utils/stepFailure.js

@@ -52,8 +52,8 @@ const KIND_COOKBOOK_LOAD_FAILURE = 'cookbook-load-failure';
  * 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
+ * step_id, type, service, operation) and forbids a step key `id` (d.983),
+ * `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
@@ -78,7 +78,7 @@ function describeStepIdentity(step, index) {
     throw new Error('[stepFailure] step is required - Expected the cookbook step (or its result) to name in a message');
   }
 
-  // `step_id` only. `readCookbookSteps` refuses a step spelling it `id`, so a
+  // `step_id` only. cookbook-core refuses a step spelling it `id` (d.983), 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;
 

package/src/utils/stepReferences.js

@@ -82,33 +82,29 @@ function resolveStepInput(step, runContext) {
 }
 
 /**
- * WHAT A TIER-1 RECIPE MAY WRITE IN `input`, checked before the run starts.
+ * WHAT A TIER-1 RECIPE MAY WRITE IN `input`, checked before the run starts —
+ * the ONE rule of that kind the format's owner does not hold.
  *
  * 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.
+ * recipe production would accept. A helper call — `{{webalizeString(…)}}`,
+ * `{{string2file(…)}}` — broke that symmetry by going QUIET where production is
+ * loud: 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. `@onlineapps/cookbook-core`
+ * accepts a helper call — it is valid in a recipe production runs — so the
+ * refusal is Tier-1's own and lives here.
+ *
+ * WHAT IS NOT HERE ANY MORE. A `{{steps.<id>}}` naming no step of the recipe,
+ * a positional `steps.0` / `steps[0]`, and a `depends_on` naming no step are
+ * refused by `@onlineapps/cookbook-core` `validateCookbook`, which
+ * `CookbookTestRunner.validateCookbook` runs FIRST. This module held its own
+ * copy of the first and the last with its own messages until d.980 — one
+ * concern on two rails (`.claude/rules/change-discipline.md` § One rail per
+ * concern).
  *
  * NO SECOND WALK. The traversal and the expression extraction are the same
  * `resolveReferencesWith()` that resolves the input for real one moment later,
@@ -127,8 +123,7 @@ function resolveStepInput(step, runContext) {
  * 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.
+ * (`resolveStepInput` above says why).
  *
  * @see api/docs/biz/40-cookbooks/variable-references.md
  * @see api/docs/governance/confirmations/cookbook-validation-placement.md
@@ -137,9 +132,6 @@ function resolveStepInput(step, runContext) {
 /** `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 `
@@ -149,76 +141,25 @@ function helperCallProblem(stepId, helperName, expression) {
     + '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
+ * Returns the FIRST problem rather than throwing: 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
+ * @param {Array<Object>} steps - the cookbook's steps, already validated by cookbook-core
  * @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);
+        const helperCall = expression.match(HELPER_CALL);
+        if (helperCall) {
+          problem = helperCallProblem(step.step_id, helperCall[1], expression);
+        }
       }
       return undefined;
     });

package/src/utils/throwawaySchema.js

@@ -12,7 +12,7 @@
  * (`change-discipline.md` § One rail per concern), and the concern here is not
  * service-specific at all: the service declares WHAT its database is in
  * `config/service/integration-contract.json`, and HOW a schema gets built from
- * that declaration is uniform (`docs/biz/00-model/uniformity-principle.md`).
+ * that declaration is uniform (`api/docs/biz/00-model/uniformity-principle.md`).
  *
  * WHAT IT SHARES WITH THE CI BUILD. Everything except one decision. The
  * migration set and its order (`resolveMigrationPlan`, `migrationOrder.js`), the