@onlineapps/conn-orch-validator 3.3.0 → 3.3.2

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [3.3.2] — 2026-08-17
+
+**ServiceStructureValidator refactor for ADR 0005 / Fáze F6 reality.**
+
+3.3.1 still required `src/app.js`, `service.port`, and `businessErrorHandler in src/app.js` — all dead after F6 removed Express. Any biz service whose validation-proof got invalidated post-F6 would hit `MISSING_APP` at Tier-1 step 1 and stall in restart loop. Surfaced when biz-meta's proof was manually invalidated in the Fáze F7 followup.
+
+### BREAKING
+
+- **v1.0 Base Service Standard**: `src/app.js` no longer required. `src/handlers/` is now the required source dir (flat or `handlers/v3/` subdir — both are canonical variants). `service.port` no longer required in `config.json`.
+- **v1.2 Business Error Handling**: `businessErrorHandler in src/app.js` check REMOVED (there is no src/app.js). Replaced with: at least one handler under `src/handlers/` imports and throws a `BusinessError` family class (`ValidationError`, `NotFoundError`, `ConflictError`, `ForbiddenError`) from `@onlineapps/service-common`. Errors flow through the wrapper's `ErrorMapper` post-A2.2, not through Express middleware.
+- **`validateSourceStructure()`**: `MISSING_APP` error replaced with `MISSING_HANDLERS`. Presence of `src/app.js` now emits a **warning** (`LEGACY_APP_JS`) — dead code that F6 removes.
+
+### Added
+
+- **v1.3 Zero-HTTP Shape (ADR 0005)** — new standard level asserting F6 cleanup landed:
+  - `src/app.js` absent
+  - `src/routes/` absent
+  - `src/middlewares/` absent
+  - `express` NOT in `package.json` dependencies
+
+### Rationale
+
+Every biz service on the platform is post-F6 (verified in Fáze F acceptance ledger). Continuing to require Express artefacts would false-positive-fail every valid v3-canonical service.
+
+### Tests
+
+Unit suite 158/158 GREEN before publish. Note: standard-level tests
+(`StandardLevels.test.js`) were rewritten in the same commit to match
+the post-F6 rules — 6 pre-existing test cases replaced with 6 matching
+the new spec.
+
+## [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.2",
   "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();

package/src/validators/ServiceStructureValidator.js

@@ -50,7 +50,9 @@ const STANDARD_LEVELS = [
       results.push({ passed: hasConfigDir(root), id: 'dir_conn_config', message: 'config/service/ or conn-config/ directory' });
       results.push({ passed: has('src'), id: 'dir_src', message: 'src/ directory' });
       results.push({ passed: has('tests'), id: 'dir_tests', message: 'tests/ directory' });
-      results.push({ passed: has('src/app.js'), id: 'file_app', message: 'src/app.js' });
+      // ADR 0005: src/handlers/ replaces src/app.js. Flat handlers/ or
+      // handlers/v3/ subdir are both valid canonical shapes.
+      results.push({ passed: has('src/handlers'), id: 'dir_handlers', message: 'src/handlers/ (v3 handler modules)' });
       results.push({ passed: has('index.js'), id: 'file_index', message: 'index.js entry point' });
 
       const configRaw = readConfigFile(root, 'config.json');
@@ -58,10 +60,11 @@ const STANDARD_LEVELS = [
       if (configRaw) {
         try {
           const cfg = JSON.parse(configRaw);
-          configValid = !!(cfg.service?.name && cfg.service?.port);
+          // ADR 0005: service.port not required post zero-HTTP. Just name.
+          configValid = !!cfg.service?.name;
         } catch { /* invalid JSON */ }
       }
-      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name + service.port' });
+      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name' });
 
       const opsRaw = readConfigFile(root, 'operations.json');
       let opsValid = false;
@@ -120,12 +123,63 @@ const STANDARD_LEVELS = [
         } catch { /* invalid JSON */ }
       }
 
-      const appContent = read('src/app.js') || '';
-      const hasErrorMiddleware = appContent.includes('businessErrorHandler');
+      // ADR 0005 / F6: businessErrorHandler was Express middleware in
+      // src/app.js. Post-F6 there is no src/app.js. Error handling now
+      // happens via BusinessError thrown from handlers → wrapper's
+      // ErrorMapper. Check: at least one handler imports a
+      // BusinessError-family class from @onlineapps/service-common.
+      const handlersDir = path.join(root, 'src', 'handlers');
+      let hasBusinessErrorUsage = false;
+      if (fs.existsSync(handlersDir)) {
+        const walk = (dir) => {
+          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory()) walk(p);
+            else if (entry.isFile() && entry.name.endsWith('.js')) {
+              const content = read(path.relative(root, p));
+              if (content && /@onlineapps\/service-common/.test(content) &&
+                  /BusinessError|ValidationError|NotFoundError|ConflictError|ForbiddenError/.test(content)) {
+                hasBusinessErrorUsage = true;
+              }
+            }
+          }
+        };
+        try { walk(handlersDir); } catch { /* ignore */ }
+      }
 
       return [
         { passed: hasServiceCommon, id: 'dep_service_common', message: '@onlineapps/service-common dependency' },
-        { passed: hasErrorMiddleware, id: 'error_middleware', message: 'businessErrorHandler middleware in src/app.js' }
+        { passed: hasBusinessErrorUsage, id: 'business_error_usage', message: 'At least one handler throws a BusinessError family from @onlineapps/service-common' }
+      ];
+    }
+  },
+  {
+    level: 'v1.3',
+    name: 'Zero-HTTP Shape (ADR 0005)',
+    since: '2026-08-17',
+    checks: (root) => {
+      const has = (p) => fs.existsSync(path.join(root, p));
+      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
+
+      // v1.3 asserts that F6/A2 cleanup landed: no dead Express surface.
+      const noAppJs = !has('src/app.js');
+      const noRoutesDir = !has('src/routes');
+      const noMiddlewaresDir = !has('src/middlewares');
+
+      const pkgRaw = read('package.json');
+      let noExpressDep = true;
+      if (pkgRaw) {
+        try {
+          const pkg = JSON.parse(pkgRaw);
+          noExpressDep = !pkg.dependencies?.express;
+        } catch { /* invalid JSON — separate check catches it */ }
+      }
+
+      return [
+        { passed: noAppJs, id: 'no_app_js', message: 'src/app.js absent (retired Express dispatch surface)' },
+        { passed: noRoutesDir, id: 'no_routes_dir', message: 'src/routes/ absent (dead HTTP route mounts)' },
+        { passed: noMiddlewaresDir, id: 'no_middlewares_dir', message: 'src/middlewares/ absent (dead Express middleware)' },
+        { passed: noExpressDep, id: 'no_express_dep', message: 'express not in package.json dependencies' }
       ];
     }
   }
@@ -594,39 +648,45 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate source code structure
+   * Validate source code structure.
+   *
+   * ADR 0005 (2026-08-17): biz containers have zero HTTP surface —
+   * no Express, no `src/app.js`, no per-op HTTP routes. The v3
+   * handler-registry model instead requires `src/handlers/` (flat
+   * or `handlers/v3/` subdir — both variants of the canonical
+   * shape) with `handler` refs from `operations.json` resolvable
+   * to real exports.
    */
   validateSourceStructure() {
-    const appPath = path.join(this.serviceRoot, 'src/app.js');
-    if (!fs.existsSync(appPath)) {
+    // Post-ADR-0005 hard requirement: at least one handler module
+    // (flat or under v3/) must exist. HandlerRegistry.validate() at
+    // bootstrap time enforces per-op resolution; here we just ensure
+    // the directory itself is present so the service has something
+    // to dispatch to.
+    const handlersFlat = path.join(this.serviceRoot, 'src/handlers');
+    if (!fs.existsSync(handlersFlat)) {
       this.errors.push({
-        type: 'MISSING_APP',
-        path: 'src/app.js',
-        message: 'Express application missing: src/app.js',
-        fix: 'Create src/app.js with Express app. See: /docs/biz/60-templates/service-template.md'
+        type: 'MISSING_HANDLERS',
+        path: 'src/handlers',
+        message: 'Handlers directory missing: src/handlers/',
+        fix: 'Create src/handlers/ with at least one v3 handler module. See: /docs/biz/60-templates/service-template.md'
       });
     } else {
-      this.info.push('✓ Found src/app.js');
+      this.info.push('✓ Found src/handlers/');
+    }
 
-      try {
-        const appContent = fs.readFileSync(appPath, 'utf-8');
-        if (appContent.includes('businessErrorHandler')) {
-          this.info.push('✓ businessErrorHandler middleware registered');
-        } else {
-          this.warnings.push({
-            type: 'MISSING_ERROR_MIDDLEWARE',
-            path: 'src/app.js',
-            message: 'businessErrorHandler middleware not found in src/app.js',
-            fix: 'Register businessErrorHandler from @onlineapps/service-common as Express error middleware. See: /docs/standards/ERROR_HANDLING.md'
-          });
-        }
-      } catch (readError) {
-        this.warnings.push({
-          type: 'UNREADABLE_APP',
-          path: 'src/app.js',
-          message: `Could not read src/app.js: ${readError.message}`
-        });
-      }
+    // src/app.js is ANTI-PATTERN post-ADR 0005 (dead Express surface).
+    // Warn if present so authors of new services notice they should
+    // remove it; existing services scheduled to be cleaned up via the
+    // Fáze F6 pass.
+    const appPath = path.join(this.serviceRoot, 'src/app.js');
+    if (fs.existsSync(appPath)) {
+      this.warnings.push({
+        type: 'LEGACY_APP_JS',
+        path: 'src/app.js',
+        message: 'src/app.js is dead code post-ADR 0005 (bootstrap no longer reads it)',
+        fix: 'Delete src/app.js; move any residual middleware into the wrapper adapter. See: /docs/biz/80-decisions/0005-no-http-in-biz-containers.md'
+      });
     }
 
     const indexPath = path.join(this.serviceRoot, 'index.js');