@onlineapps/conn-orch-validator 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [3.3.1] — 2026-08-17
+
+**Tier-1 step 5 refactor: retire HTTP `/health` probe per ADR 0005.**
+
+Fáze F5 surfaced this in the live rollout: after service-wrapper 3.4.x removed Express init, every biz Tier-1 validation failed step 5 (`Health check failed`) because `ServiceReadinessValidator.checkHealth()` still called `fetch(url + '/health')`. There is nothing listening under ADR 0005 — biz containers have zero HTTP surface.
+
+### BREAKING (behaviour of `validateReadiness()`)
+
+- `checkHealth()` method removed.
+- `service.healthEndpoint` option removed (no consumer left).
+- `service.url` still accepted but no longer consumed (kept in results.serviceUrl for report annotation only).
+- Weight rebalance: `operations` 60 → 80 (absorbs the retired `health` 20 pts). `cookbook` and `registry` unchanged. Total remains 100.
+- `results.checks.health` no longer emitted.
+
+### Helper API change (`createServiceReadinessTests`)
+
+- No longer starts an Express `app.listen(testPort, ...)`.
+- Removed `options.testPort` (no port to bind).
+- Removed the `health endpoint responds correctly` test.
+- Removed `result.checks.health?.passed` assertion.
+- Existing biz-side test files that consume this helper (`api_biz/hello-service`, `api_biz/converter`, `api_biz/ingest` under `tests/bootstrap/`) continue to work unchanged — the helper signature stays `createServiceReadinessTests(testsDir, options)`, only the internal setup shrinks.
+
+### Rationale
+
+Tier-1 runs in Phase 0.2 (very early — before the wrapper opens any connectors). Under ADR 0005 there is no HTTP listener to probe *ever*, in any phase; runtime liveness is observed by Registry via the MQ heartbeat + Redis projection path (`infrastructureHealthTracker`) *after* Phase 0.10. Tier-1 has no meaningful health signal to check — the honest fix is to drop the check.
+
+Structure + config + operations correctness (steps 1-3) plus cookbook execution (step 4) already prove service readiness; `operations` at 80 pts + optional `cookbook` and `registry` cover the remaining 20 pts.
+
+### Tests
+
+Full unit suite (158 tests, 11 suites) GREEN with the retired HTTP probe removed. No new tests needed — `checkHealth` had no isolated test; behaviour was exercised implicitly.
+
 ## [3.3.0] — 2026-08-17
 
 **Env-var contract rename per env-conventions.md.** Details: `api/docs/biz/60-templates/env-conventions.md`, `api/docs/biz/40-cookbooks/test-env-vars.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "bin": {

package/src/ServiceReadinessValidator.js

@@ -11,8 +11,19 @@ const CookbookTestUtils = require('./CookbookTestUtils');
  * per-operation endpoints. The HTTP loopback check was removed when v3
  * adopted in-process handler invocation.
  *
+ * ADR 0005 (2026-08-17): biz containers have zero HTTP surface. The
+ * runtime `health` check (previously `fetch(url + '/health')`) is
+ * retired because there is nothing listening. Runtime health is
+ * observed by Registry via the MQ heartbeat + Redis projection path
+ * (see api_services_registry/src/services/infrastructureHealthTracker)
+ * — outside Tier-1's scope, and later in the boot sequence anyway
+ * (Tier-1 runs in Phase 0.2, heartbeat in Phase 0.10). The 20 points
+ * previously spent on `health` fold into `operations` so total stays
+ * at 100.
+ *
  * @see /api/docs/architecture/biz-service-invocation-model.md §5.3
  * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (input probe contract)
+ * @see /api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md
  */
 class ServiceReadinessValidator {
   constructor(options = {}) {
@@ -24,14 +35,16 @@ class ServiceReadinessValidator {
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
     // Core checks ALWAYS run, optional checks run if testCookbook/registry provided
     // See: /shared/connector/conn-orch-validator/README.md for usage pattern
-    // v3: per-op HTTP endpoint probing is retired. Operations are dispatched in-process
-    // via the handler registry. The 30-point weight previously spent on `endpoints`
-    // is folded into `operations` so the total stays at 100.
+    //
+    // Weight allocation post-ADR-0005:
+    //   operations: 80 — was 60; absorbed the 20 pts from retired `health`.
+    //   cookbook:   15 — unchanged (optional).
+    //   registry:    5 — unchanged (optional).
+    // The retired `health` HTTP probe is documented in the class JSDoc above.
     this.checks = {
-      operations: { weight: 60, required: true },   // operations.json v3 structure valid
-      health: { weight: 20, required: true },       // health check works
-      cookbook: { weight: 15, required: false },    // OPTIONAL - cookbook valid (with mocks)
-      registry: { weight: 5, required: false }      // OPTIONAL - registry compatible (MockRegistry)
+      operations: { weight: 80, required: true },   // operations.json v3 structure valid
+      cookbook:   { weight: 15, required: false },  // OPTIONAL - cookbook valid (with mocks)
+      registry:   { weight: 5,  required: false }   // OPTIONAL - registry compatible (MockRegistry)
     };
   }
 
@@ -45,8 +58,7 @@ class ServiceReadinessValidator {
       url,
       operations,
       registry,
-      testCookbook,
-      healthEndpoint = '/health'
+      testCookbook
     } = service;
 
     const results = {
@@ -77,13 +89,12 @@ class ServiceReadinessValidator {
     // 2. (v3) Per-op HTTP endpoint probing retired — operations are dispatched
     //    in-process via the handler registry. No network call per operation.
 
-    // 3. Verify health check
-    results.checks.health = await this.checkHealth(url + healthEndpoint);
-    if (results.checks.health.passed) {
-      results.score += this.checks.health.weight;
-    } else if (this.checks.health.required) {
-      results.errors.push('Health check failed');
-    }
+    // 3. (ADR 0005) Runtime health check retired — biz containers have no HTTP
+    //    surface. Runtime liveness flows via MQ heartbeat to Registry's
+    //    infrastructureHealthTracker; consumed by BusinessReadinessChecker
+    //    (post Fáze A2.3). Tier-1 cannot observe that state because it runs
+    //    in Phase 0.2, before the heartbeat publisher starts in Phase 0.10.
+    //    The 20-point weight moved to `operations` above.
 
     // 4. Test cookbook execution (if provided)
     if (testCookbook) {
@@ -196,35 +207,8 @@ class ServiceReadinessValidator {
     }
   }
 
-  /**
-   * Check health endpoint via Node 18+ global fetch (no external HTTP client).
-   */
-  async checkHealth(healthUrl) {
-    try {
-      const response = await fetch(healthUrl, {
-        method: 'GET',
-        signal: AbortSignal.timeout(5000)
-      });
-
-      let data = null;
-      try {
-        data = await response.json();
-      } catch (_) {
-        // health endpoint may return non-JSON; keep data null and rely on status.
-      }
-
-      return {
-        passed: response.status === 200,
-        status: response.status,
-        data
-      };
-    } catch (error) {
-      return {
-        passed: false,
-        error: error.message
-      };
-    }
-  }
+  // checkHealth() removed 2026-08-17 per ADR 0005 (no HTTP surface in
+  // biz containers). See class JSDoc header for full rationale.
 
   /**
    * Check cookbook structure validity

package/src/helpers/createServiceReadinessTests.js

@@ -1,18 +1,26 @@
 /**
  * Create Service Readiness Integration Tests
  *
- * Generic test suite that validates service HTTP API readiness.
- * Works for ALL business services - no service-specific code needed.
+ * Generic test suite that validates service configuration + operations
+ * are ready for production. Works for ALL business services — no
+ * service-specific code needed.
+ *
+ * ADR 0005 (2026-08-17): biz containers have zero HTTP surface. This
+ * helper NO LONGER starts an Express app, NO LONGER binds a test port,
+ * NO LONGER fetches `/health`. What it verifies:
+ *   - Service structure valid (via ServiceStructureValidator)
+ *   - operations.json valid v3 shape (handler, bundle_scope, input, output)
+ *   - Optional: cookbook validation + registry compatibility
  *
  * @module helpers/createServiceReadinessTests
  *
  * Usage:
  *   const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
- *   createServiceReadinessTests(__dirname);  // Pass tests/integration directory
+ *   createServiceReadinessTests(__dirname);  // Pass tests/bootstrap directory
  *
  * Related:
- * - /docs/standards/TESTING.md - Testing standards
- * - /tests/TESTING.md - SPOT principles
+ * - /docs/biz/80-decisions/0005-no-http-in-biz-containers.md
+ * - /docs/biz/00-model/service-shape.md (zero-HTTP canonical shape)
  * - /shared/connector/conn-orch-validator/README.md - Package documentation
  */
 
@@ -27,24 +35,22 @@ const { ServiceStructureValidator } = require('../validators/ServiceStructureVal
 /**
  * Create service readiness integration test suite
  *
- * @param {string} testsDir - Path to tests/integration directory (use __dirname)
+ * @param {string} testsDir - Path to tests/bootstrap directory (use __dirname)
  * @param {Object} [options] - Optional configuration
- * @param {number} [options.testPort=5556] - Port for test server
  * @param {boolean} [options.includeOptionalChecks=true] - Include cookbook & registry checks
  * @param {number} [options.timeout=15000] - Test timeout in ms
  *
  * @example
- * // In services/my-service/tests/integration/service-readiness.test.js
+ * // In services/my-service/tests/bootstrap/service-readiness.test.js
  * const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
  *
  * createServiceReadinessTests(__dirname);
  */
 function createServiceReadinessTests(testsDir, options = {}) {
-  // Calculate service root (2 levels up from tests/integration/)
+  // Calculate service root (2 levels up from tests/bootstrap/)
   const serviceRoot = path.resolve(testsDir, '../..');
 
   const {
-    testPort = 5556,
     includeOptionalChecks = true,
     timeout = 15000
   } = options;
@@ -72,58 +78,24 @@ function createServiceReadinessTests(testsDir, options = {}) {
   };
   const configPath = resolveConfig('config.json');
   const operationsPath = resolveConfig('operations.json');
-  const appPath = path.join(serviceRoot, 'src/app.js');
 
   const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
-  const app = require(appPath);
 
   // Extract metadata from config
   const serviceName = config.service.name;
   const serviceVersion = config.service.version;
-  const healthEndpoint = config.wrapper?.health?.endpoint || '/health';
 
-  // Create test suite
   describe(`${serviceName} Service Readiness @integration`, () => {
-    let server;
-    let baseUrl;
-
-    beforeAll(async () => {
-      // Start service for testing
-      server = await new Promise((resolve) => {
-        const srv = app.listen(testPort, () => {
-          baseUrl = `http://127.0.0.1:${testPort}`;
-          console.log(`\n✓ Test server started: ${baseUrl}\n`);
-          resolve(srv);
-        });
-      });
-    });
-
-    afterAll(async () => {
-      // Stop service
-      if (server) {
-        await new Promise((resolve) => {
-          server.close(() => {
-            console.log('\n✓ Test server stopped\n');
-            resolve();
-          });
-        });
-      }
-    });
-
     test('service passes readiness validation', async () => {
       // Validator expects flat operations object
       const operationsFlat = operations.operations || operations;
 
-      // Prepare optional checks
       let mockRegistry = null;
       let testCookbook = null;
 
       if (includeOptionalChecks) {
-        // Create MockRegistry for registry compatibility check (+5 points)
         mockRegistry = new MockRegistry();
-
-        // Auto-generate test cookbook from operations (+15 points)
         testCookbook = {
           version: '1.0.0',
           steps: Object.entries(operationsFlat).map(([name, op]) => ({
@@ -137,19 +109,15 @@ function createServiceReadinessTests(testsDir, options = {}) {
         };
       }
 
-      // Run readiness validation
       const validator = new ServiceReadinessValidator({ logger: console });
       const result = await validator.validateReadiness({
         name: serviceName,
         version: serviceVersion,
-        url: baseUrl,
         operations: operationsFlat,
-        healthEndpoint: healthEndpoint,
         testCookbook: testCookbook,
         registry: mockRegistry
       });
 
-      // Log detailed results
       console.log('\n📊 Readiness Validation Results:');
       console.log(`   Score: ${result.score}/100`);
       console.log(`   Ready: ${result.ready ? '✅' : '❌'}`);
@@ -167,7 +135,6 @@ function createServiceReadinessTests(testsDir, options = {}) {
       }
       console.log('');
 
-      // Assertions
       expect(result).toHaveProperty('ready');
       expect(result).toHaveProperty('score');
       expect(result).toHaveProperty('checks');
@@ -177,26 +144,15 @@ function createServiceReadinessTests(testsDir, options = {}) {
 
       if (includeOptionalChecks) {
         expect(result.score).toBe(100);
-        expect(result.checks.health?.passed).toBe(true);
         expect(result.checks.operations?.passed).toBe(true);
         expect(result.checks.cookbook?.passed).toBe(true);
         expect(result.checks.registry?.passed).toBe(true);
       } else {
         expect(result.score).toBeGreaterThanOrEqual(80);
-        expect(result.checks.health?.passed).toBe(true);
         expect(result.checks.operations?.passed).toBe(true);
       }
     }, timeout);
 
-    test('health endpoint responds correctly', async () => {
-      const response = await fetch(`${baseUrl}${healthEndpoint}`);
-      const data = await response.json();
-
-      expect(response.status).toBe(200);
-      expect(data).toHaveProperty('status');
-      expect(data.status).toBe('healthy');
-    });
-
     test('service has valid operations specification (v3)', () => {
       expect(operations).toBeDefined();
       expect(operations.operations || operations).toBeDefined();