@onlineapps/conn-orch-validator 4.0.0 → 5.0.0-rc.1

package/CHANGELOG.md

@@ -7,6 +7,96 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 > ⚠ Neither this entry nor the connector-step work of `dcddb862` is published.
 > The last version on NPM is 3.3.2, so **no biz CI run sees any of it yet**.
 
+### BREAKING — a cookbook step spelling its identifier `id` is refused (DÁVKA 77 A3)
+
+`format.md` § Steps has banned `id` since v2.1; the code accepted it anyway, which
+is the fallback `architecture-principles.md` §3 forbids. The whole tree was
+measured compliant first (`automation-gates.md` §3 — the gate arrives with the
+compliance, never ahead of it): 79 cookbook files, 78 pass, one does not.
+
+```
+[CookbookFormat] step "<step_id|#N>" carries "id" - Expected: "step_id" only
+(api/docs/biz/40-cookbooks/format.md § Steps). Fix: rename "id" to "step_id"
+```
+
+- `normalizeCookbookSteps` throws on any step carrying `id`, with or without a
+  `step_id` beside it, and the V2 object shape no longer writes `id` back onto
+  the step it normalises.
+- `CookbookTestUtils.validateCookbook` answers with a list rather than an
+  exception, so the refusal arrives there as one more entry in `errors`.
+- `stepIdentityOf` reads `step_id` only.
+- `createServiceReadinessTests` synthesised steps with `id`, so the helper
+  rejected its own output; it now emits `step_id`.
+
+The single file that fails today is `api_biz/meta/tests/cookbooks/list-tenants.json`
+(step `test_list_tenants`, carries both). This package is not published until it
+is fixed.
+
+### BREAKING — a step result carries `step_id` only (DÁVKA 77 A)
+
+`CookbookTestRunner` emitted both `id` and `step_id` on every step result. Two
+names for one thing means every reader has to know both, and the one that was
+`undefined` for conforming cookbooks is what reached a production log as
+`Step undefined`. Measured before removing it: no run artefact carries a step
+identifier at all — the validation proof, `conn-runtime/validation-failure.json`
+and the integration-run artefact hold counts only — and the sole readers of
+`result.id` in the workspace were inside this package.
+
+- `result.id` is gone. Read `result.step_id`.
+- `runPreValidation`'s `failedSteps[]` entries carry `step_id`, not `id`; the
+  `biz-ci-gate run-prevalidation` failure line reads it from there.
+- `describeStepIdentity` no longer falls back to `id`: a step that carries one
+  is refused upstream, so reading it would only put the retired name back into
+  the diagnostics. Such a step is now named by position.
+
+### Changed (minor) — `service.port` is no longer required (DÁVKA 75 B)
+
+ADR 0005 removed the HTTP surface from biz containers. Nothing listens, so the
+port has no consumer — yet `ServiceStructureValidator` step 1 failed a service
+that did not declare one, forcing every repo to keep a number nobody reads. That
+is the inverse of `change-discipline.md` § "Removing something removes its
+declaration".
+
+- `service.port` is dropped from `validateConfigStructure`'s required fields. A
+  config without it now passes step 1.
+- A config that still declares one gets a **warning**, `ORPHANED_CONFIG_FIELD`,
+  naming ADR 0005 and the fix (delete the field). Silence would leave the eight
+  stale declarations recorded in `api/docs/biz/00-model/service-shape.md`
+  invisible, which `automation-gates.md` §5 calls a defect. It never fails a
+  build.
+- The conformant fixture no longer declares a port, and its README says why.
+
+A relaxation, so **minor**: a config that passed before still passes.
+
+### Changed (minor) — one name for a step: `step_id` (DÁVKA 75 A)
+
+`api/docs/biz/40-cookbooks/format.md` requires `step_id` and bans `id`. Measured
+2026-08-30 across the whole workspace — 101 steps in 77 cookbook files: 94 carry
+`step_id` only, 6 carry `id` only, 1 carries both. All six `id`-only steps were
+this package's own fixtures; the one carrying both is
+`api_biz/meta/tests/cookbooks/list-tenants.json`, another repo's file.
+
+- The four fixture cookbooks and the inline cookbooks in four suites now use
+  `step_id`, and the assertions read `result.step_id`.
+- `CookbookTestUtils.validateCookbook` **rejected 100 % of the real cookbooks**:
+  it demanded `id`, and it knew only the array shape, so every V2 object-shaped
+  cookbook came back `"Steps array is required"`. It is reachable from
+  `ServiceReadinessValidator.checkCookbookExecution`, so a service using the
+  readiness wrapper was told its correct cookbooks were broken. Raw proof before
+  the fix: `tester-helpers.json` → `["Step 0: id is required", …×5]`,
+  `property/list-statements.json` → `["Steps array is required"]`.
+- Both shapes now go through one owner, `utils/cookbookFormat.normalizeCookbookSteps`,
+  which `CookbookTestRunner.normalizeSteps` also delegates to — the two entry
+  points can no longer disagree about what a cookbook's steps are.
+- `stepIdentityOf()` reads `step_id`, then `id`. **`id` is still accepted**;
+  rejecting it is a separate decision for the owner.
+- What this package synthesises (`generateTestCookbook`, `createWorkflowMessage`,
+  `createControlFlowStep`) emits `step_id` only, and `compareCookbooks` reports
+  differences as `steps[i].step_id`.
+
+`result.id` is still emitted by `CookbookTestRunner` alongside `result.step_id`.
+Whether it survives is a result-contract change and is the owner's call.
+
 ### Fixed — validator findings pointed at an archived document (DÁVKA 51)
 
 `ServiceStructureValidator` sent readers of five findings to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "4.0.0",
+  "version": "5.0.0-rc.1",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "bin": {
@@ -24,12 +24,7 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/service-validator-core": "1.0.14",
-    "@onlineapps/runtime-config": "1.0.2",
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "amqplib": "^0.10.9",
-    "joi": "^17.9.0"
+    "@onlineapps/service-validator-core": "1.0.15"
   },
   "devDependencies": {
     "jest": "^29.5.0"

package/src/CookbookTestRunner.js

@@ -6,9 +6,9 @@ const crypto = require('crypto');
 const MockMQClient = require('./mocks/MockMQClient');
 const MockRegistry = require('./mocks/MockRegistry');
 const { resolveHeaders } = require('./utils/resolveHeaders');
-const { checkCookbookFormatVersion } = require('./utils/cookbookFormat');
+const { checkCookbookFormatVersion, normalizeCookbookSteps } = require('./utils/cookbookFormat');
 const { getTestNamespace } = require('./utils/testNamespace');
-const { describeStepFailure } = require('./utils/stepFailure');
+const { describeStepFailure, describeStepIdentity } = require('./utils/stepFailure');
 
 /**
  * The step's stopwatch, spelled out. A single total hid the fact that
@@ -124,8 +124,8 @@ class CookbookTestRunner {
     // Execute steps
     const cookbookName = cookbookData.description || 'Unnamed';
     const stepResults = [];
-    for (const step of stepsArray) {
-      const stepResult = await this.executeStep(step, testConfig);
+    for (const [stepIndex, step] of stepsArray.entries()) {
+      const stepResult = await this.executeStep(step, testConfig, stepIndex);
       // Which cookbook this step came from. Without it a failed step in the
       // aggregate is an id with no file behind it, and a service can carry a
       // dozen cookbooks (utils/stepFailure.js).
@@ -210,13 +210,23 @@ class CookbookTestRunner {
   /**
    * Execute single step
    */
-  async executeStep(step, testConfig) {
+  async executeStep(step, testConfig, stepIndex = 0) {
     const startTime = Date.now();
 
-    this.logger.info(`Executing step: ${step.id || 'unnamed'} (${step.operation})`);
+    // ONE label for this step, resolved once. `step.id` alone was undefined for
+    // every cookbook that follows the required v2.1 shape (`step_id`), so the
+    // live biz-converter log read `Step undefined: FAILED …` about a cookbook
+    // that is correct. Owner of the rule: utils/stepFailure.js.
+    const stepLabel = describeStepIdentity(step, stepIndex);
+
+    this.logger.info(`Executing step: ${stepLabel} (${step.operation})`);
 
     const result = {
-      id: step.id,
+      // The identifier the format requires, plus the position, so the aggregate
+      // error list can name the step without re-deriving anything. `id` was
+      // emitted alongside it until 2026-08-30; one thing, one name.
+      step_id: step.step_id,
+      stepIndex,
       operation: step.operation,
       passed: false,
       // Three separate numbers, because they answer different questions.
@@ -273,13 +283,13 @@ class CookbookTestRunner {
       });
 
       if (result.passed) {
-        this.logger.info(`Step ${step.id}: PASSED (${describeStepTiming(result)})`);
+        this.logger.info(`Step ${stepLabel}: PASSED (${describeStepTiming(result)})`);
       } else {
         // A verdict without its reason is a silent gate (automation-gates.md
         // §5). Until 2026-08-29 this line said only "FAILED (1101ms)" and the
         // reason — held in result.validationErrors or result.error — reached
         // nobody, which made a failed biz-hello boot undiagnosable from logs.
-        this.logger.error(`Step ${step.id}: FAILED (${describeStepTiming(result)}) — ${describeStepFailure(result)}`);
+        this.logger.error(`Step ${stepLabel}: FAILED (${describeStepTiming(result)}) — ${describeStepFailure(result)}`);
       }
 
     } catch (error) {
@@ -291,7 +301,7 @@ class CookbookTestRunner {
       result.handlerDurationMs = 0;
       result.passed = false;
 
-      this.logger.error(`Step ${step.id}: ERROR - ${error.message}\n${error.stack}`);
+      this.logger.error(`Step ${stepLabel}: ERROR - ${error.message}\n${error.stack}`);
     }
 
     return result;
@@ -692,25 +702,10 @@ class CookbookTestRunner {
    * Supports V1 (steps as array) and V2 (steps as object keyed by step_id)
    */
   normalizeSteps(steps) {
-    if (!steps) {
-      return [];
-    }
-
-    // V1 format: steps is already an array
-    if (Array.isArray(steps)) {
-      return steps;
-    }
-
-    // V2 format: steps is an object keyed by step_id
-    if (typeof steps === 'object') {
-      return Object.entries(steps).map(([stepId, step]) => ({
-        ...step,
-        step_id: stepId,
-        id: stepId // Keep both for backward compatibility
-      }));
-    }
-
-    return [];
+    // The rule lives in utils/cookbookFormat — the same owner
+    // CookbookTestUtils.validateCookbook now reads, so the two entry points
+    // cannot disagree about what a cookbook's steps are.
+    return normalizeCookbookSteps(steps);
   }
 
   /**
@@ -748,8 +743,8 @@ class CookbookTestRunner {
     }
 
     for (const step of stepsArray) {
-      if (!step.service) throw new Error(`Step ${step.step_id || step.id || 'unknown'} must have service`);
-      if (!step.operation) throw new Error(`Step ${step.step_id || step.id || 'unknown'} must have operation`);
+      if (!step.service) throw new Error(`Step ${step.step_id || 'unknown'} must have service`);
+      if (!step.operation) throw new Error(`Step ${step.step_id || 'unknown'} must have operation`);
     }
 
     return true;

package/src/CookbookTestUtils.js

@@ -1,6 +1,11 @@
 'use strict';
 
-const { MIN_COOKBOOK_FORMAT_VERSION, checkCookbookFormatVersion } = require('./utils/cookbookFormat');
+const {
+  MIN_COOKBOOK_FORMAT_VERSION,
+  checkCookbookFormatVersion,
+  normalizeCookbookSteps,
+  stepIdentityOf
+} = require('./utils/cookbookFormat');
 
 /**
  * CookbookTestUtils - Utilities for cookbook testing
@@ -16,7 +21,7 @@ class CookbookTestUtils {
         version: MIN_COOKBOOK_FORMAT_VERSION,
         steps: options.steps || [
           {
-            id: 'step1',
+            step_id: 'step1',
             type: 'task',
             service: options.serviceName || 'test-service',
             operation: 'testOperation',
@@ -43,7 +48,7 @@ class CookbookTestUtils {
 
     for (let i = 1; i <= stepCount; i++) {
       steps.push({
-        id: `step${i}`,
+        step_id: `step${i}`,
         type: 'task',
         service: services[i % services.length],
         operation: `operation${i}`,
@@ -80,12 +85,26 @@ class CookbookTestUtils {
       errors.push(versionProblem);
     }
 
-    if (!cookbook.steps || !Array.isArray(cookbook.steps)) {
+    // Both documented shapes, through the one owner of that rule. Requiring an
+    // array here rejected every V2 object-shaped cookbook, and requiring `id`
+    // rejected every cookbook that follows format.md — measured 2026-08-30,
+    // that was 100 % of the tree.
+    let steps;
+    try {
+      steps = normalizeCookbookSteps(cookbook.steps);
+    } catch (error) {
+      // The refusal is the finding. This entry point answers with a list, not
+      // an exception, so the message becomes one more error in that list.
+      errors.push(error.message);
+      return { valid: false, errors };
+    }
+
+    if (steps.length === 0) {
       errors.push('Steps array is required');
     } else {
-      cookbook.steps.forEach((step, index) => {
-        if (!step.id) {
-          errors.push(`Step ${index}: id is required`);
+      steps.forEach((step, index) => {
+        if (!stepIdentityOf(step)) {
+          errors.push(`Step ${index}: step_id is required`);
         }
         if (!step.type) {
           errors.push(`Step ${index}: type is required`);
@@ -118,8 +137,8 @@ class CookbookTestUtils {
     }
 
     // Compare steps
-    const steps1 = cookbook1.steps || [];
-    const steps2 = cookbook2.steps || [];
+    const steps1 = normalizeCookbookSteps(cookbook1.steps);
+    const steps2 = normalizeCookbookSteps(cookbook2.steps);
 
     if (steps1.length !== steps2.length) {
       differences.push({
@@ -135,11 +154,11 @@ class CookbookTestUtils {
       const step1 = steps1[i];
       const step2 = steps2[i];
 
-      if (step1.id !== step2.id) {
+      if (stepIdentityOf(step1) !== stepIdentityOf(step2)) {
         differences.push({
-          field: `steps[${i}].id`,
-          cookbook1: step1.id,
-          cookbook2: step2.id
+          field: `steps[${i}].step_id`,
+          cookbook1: stepIdentityOf(step1),
+          cookbook2: stepIdentityOf(step2)
         });
       }
 
@@ -198,7 +217,7 @@ class CookbookTestUtils {
    */
   static createControlFlowStep(type, options = {}) {
     const baseStep = {
-      id: options.id || `${type}-step-${Date.now()}`,
+      step_id: options.step_id || options.id || `${type}-step-${Date.now()}`,
       type
     };
 
@@ -208,7 +227,7 @@ class CookbookTestUtils {
           ...baseStep,
           items: options.items || '$api_input.items',
           body: options.body || {
-            id: 'foreach-body',
+            step_id: 'foreach-body',
             type: 'task',
             service: 'test-service',
             operation: 'processItem'
@@ -220,18 +239,18 @@ class CookbookTestUtils {
           ...baseStep,
           condition: options.condition || '$api_input.type',
           cases: options.cases || [
-            { value: 'type1', step: { id: 'case1', type: 'task', service: 'service1' } },
-            { value: 'type2', step: { id: 'case2', type: 'task', service: 'service2' } }
+            { value: 'type1', step: { step_id: 'case1', type: 'task', service: 'service1' } },
+            { value: 'type2', step: { step_id: 'case2', type: 'task', service: 'service2' } }
           ],
-          default: options.default || { id: 'default', type: 'task', service: 'default-service' }
+          default: options.default || { step_id: 'default', type: 'task', service: 'default-service' }
         };
 
       case 'fork_join':
         return {
           ...baseStep,
           branches: options.branches || [
-            { id: 'branch1', type: 'task', service: 'service1' },
-            { id: 'branch2', type: 'task', service: 'service2' }
+            { step_id: 'branch1', type: 'task', service: 'service1' },
+            { step_id: 'branch2', type: 'task', service: 'service2' }
           ],
           join: options.join || { strategy: 'merge' }
         };

package/src/cli/biz-ci-gate.js

@@ -334,7 +334,7 @@ async function runRunPreValidation(options) {
 
   if (!outcome.ok) {
     for (const step of outcome.failedSteps) {
-      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${step.id}: ${step.error}\n`);
+      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${step.step_id}: ${step.error}\n`);
       for (const validationError of step.validationErrors) {
         process.stderr.write(`[BizCiGate]   * ${validationError}\n`);
       }

package/src/helpers/createServiceReadinessTests.js

@@ -103,7 +103,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
           // § Required fields), otherwise this helper rejects its own output.
           version: MIN_COOKBOOK_FORMAT_VERSION,
           steps: Object.entries(operationsFlat).map(([name, op]) => ({
-            id: `test-${name}`,
+            step_id: `test-${name}`,
             type: 'task',
             service: serviceName,
             operation: name,

package/src/utils/cookbookFormat.js

@@ -88,8 +88,85 @@ function checkCookbookFormatVersion(version) {
   return null;
 }
 
+/**
+ * Normalise a cookbook's `steps` into the array shape the rest of the package
+ * works with, whichever of the two documented shapes it arrives in, and REFUSE
+ * a step that spells its identifier `id`.
+ *
+ * format.md § Steps documents an array of steps, each carrying `step_id`, and
+ * bans `id` outright. Accepting both is how a tree ends up with two names for
+ * one thing: measured 2026-08-30, 101 steps in 77 files carried `step_id` and
+ * six carried `id`, and every reader had to know about both. The V2 object
+ * shape keys the same steps by their `step_id`, so normalising it writes that
+ * key back onto the step — and nothing else.
+ *
+ * Refusal is loud, not lenient: 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, at authoring time or at runtime. The
+ * adapter that used to write `id = step_id` (`normalizeStepForExecutor`) went
+ * with the executor it fed, and `@onlineapps/cookbook-executor` itself was
+ * deleted on 2026-08-31 — WorkflowOrchestrator is the single owner of cookbook
+ * execution and reads `step_id`. So this refusal is the whole rule, not one
+ * half of it: `id` is banned by format.md § Steps, full stop.
+ *
+ * @param {*} steps the raw value of the cookbook's top-level `steps`
+ * @returns {object[]} the steps as an array; `[]` for anything else
+ * @throws {Error} when any step carries `id`
+ */
+function normalizeCookbookSteps(steps) {
+  if (!steps) {
+    return [];
+  }
+
+  let normalized;
+  if (Array.isArray(steps)) {
+    normalized = steps;
+  } else if (typeof steps === 'object') {
+    normalized = Object.entries(steps).map(([stepId, step]) => ({
+      ...step,
+      step_id: stepId
+    }));
+  } else {
+    return [];
+  }
+
+  normalized.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 `
+        + `(${DOC_REFERENCE.replace('§ Required fields', '§ Steps')}). Fix: rename "id" to "step_id"`
+      );
+    }
+  });
+
+  return normalized;
+}
+
+/**
+ * The identifier a step declares. `step_id` is the ONLY spelling the format
+ * allows; `normalizeCookbookSteps` refuses a step that carries `id`, so nothing
+ * downstream needs to know that name ever existed.
+ *
+ * @param {object} step one normalised step
+ * @returns {string|null} the declared identifier, or `null` when it declares none
+ */
+function stepIdentityOf(step) {
+  if (!step || typeof step !== 'object') {
+    return null;
+  }
+  if (typeof step.step_id === 'string' && step.step_id.length > 0) {
+    return step.step_id;
+  }
+  return null;
+}
+
 module.exports = {
   MIN_COOKBOOK_FORMAT_VERSION,
   checkCookbookFormatVersion,
-  compareVersions
+  compareVersions,
+  normalizeCookbookSteps,
+  stepIdentityOf
 };

package/src/utils/preValidation.js

@@ -110,7 +110,7 @@ async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGen
     const failedSteps = results.steps
       .filter((step) => !step.passed)
       .map((step) => ({
-        id: step.id || step.operation,
+        step_id: step.step_id || step.operation,
         error: describeStepError(step.error),
         validationErrors: step.validationErrors || []
       }));

package/src/utils/stepFailure.js

@@ -17,6 +17,40 @@
  * (automation-gates.md §5 — silence is a defect).
  */
 
+/**
+ * Which step this is — for a log line, an error list, anything a human reads.
+ *
+ * `api/docs/biz/40-cookbooks/format.md` § Required fields makes `step_id` THE
+ * identifier of a v2.1 step and bans `id` outright ("an entry carrying `id`
+ * instead of `step_id` throws"). CookbookTestRunner read `step.id` anyway, so
+ * 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).
+ *
+ * @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"
+ */
+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.
+  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}`;
+}
+
 /**
  * Why this step failed, in one line, from whichever field holds it.
  *
@@ -65,9 +99,11 @@ function describeStepFailure(stepResult) {
 function describeStepFailureWithContext(stepResult) {
   const reason = describeStepFailure(stepResult);
   const cookbook = stepResult.cookbook || 'unknown cookbook';
-  const stepId = stepResult.id || stepResult.step_id || 'unnamed step';
+  // 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}`;
 }
 
-module.exports = { describeStepFailure, describeStepFailureWithContext };
+module.exports = { describeStepIdentity, describeStepFailure, describeStepFailureWithContext };

package/src/validators/ServiceStructureValidator.js

@@ -549,10 +549,16 @@ class ServiceStructureValidator {
    * Note: service.version is now read from package.json (Single Source of Truth)
    */
   validateConfigStructure(config) {
-    // Required fields (version comes from package.json, not config.json)
+    // Required fields (version comes from package.json, not config.json).
+    //
+    // `service.port` was required here until 2026-08-30. ADR 0005 removed the
+    // HTTP surface from biz containers, so nothing listens and the number has
+    // no consumer — requiring it forced every repo to keep a declaration that
+    // means nothing, which is what `change-discipline.md` § "Removing something
+    // removes its declaration" exists to prevent. Absence is now correct;
+    // presence is reported below as a warning, never as a failure.
     const requiredFields = [
-      'service.name',
-      'service.port'
+      'service.name'
     ];
 
     for (const field of requiredFields) {
@@ -573,6 +579,21 @@ class ServiceStructureValidator {
       }
     }
 
+    // A port that is still declared is a stale declaration, not a failure. Say
+    // so out loud: `automation-gates.md` §5 — a check that stays silent about a
+    // thing it can see is a false guarantee, and the eight services measured in
+    // api/docs/biz/00-model/service-shape.md still carry the field.
+    if (config.service?.port !== undefined) {
+      this.warnings.push({
+        type: 'ORPHANED_CONFIG_FIELD',
+        path: 'config/service/config.json',
+        field: 'service.port',
+        value: config.service.port,
+        message: 'service.port is declared but nothing listens: ADR 0005 removed the HTTP surface from biz containers',
+        fix: 'Remove "port" from the "service" section of config.json'
+      });
+    }
+
     // Validate service name format
     if (config.service?.name) {
       if (!/^[a-z][a-z0-9-]*$/.test(config.service.name)) {