@onlineapps/conn-orch-validator 2.0.33 → 3.0.0

package/docs/DESIGN.md

@@ -1,134 +1,80 @@
-# Connector-Testing Design Document
+# conn-orch-validator — Design
 
 ## Purpose
 
-The conn-orch-validator package provides a unified testing and validation framework for OA Drive microservices. It serves three critical functions:
+Validation framework for OA Drive microservices. Drives two flows:
 
-1. **Development Testing** - Mock infrastructure for isolated service testing
-2. **Production Validation** - On-the-fly validation of new services during registration
-3. **Service Readiness** - Complete verification before deployment
+1. **Pre-validation** (Tier 1) — runs during `service-wrapper` startup. Verifies
+   structure (config files, package.json), readiness (endpoints respond, health
+   works) and produces a signed `validation-proof.json` stored under
+   `conn-runtime/`.
+2. **Readiness checks** — reusable probes (`createServiceReadinessTests`,
+   `createPreValidationTests`) consumable from unit/component test suites
+   of individual biz services.
 
-## Key Principles
+The single source of truth for service endpoint metadata is
+[`operations.json`](../../../docs/standards/operations-registry-contract.md).
+OpenAPI iteration (`paths`/`operationId`) is NOT supported — that legacy
+surface was removed together with the now-retired `ServiceValidator` /
+`TestOrchestrator` / `ServiceTestHarness` classes.
 
-### No Duplication
-- Does NOT duplicate tests from individual connectors
-- Uses existing connector functionality where available
-- Focuses on integration and orchestration
+## Key Principles
 
-### Production-Ready
-- Same code used in development AND production
-- Validates services before they join the ecosystem
-- Ensures cookbook compatibility
+- **No duplication** — does not re-test individual connector logic; focuses on
+  integration, readiness and proof generation.
+- **Production-ready** — the exact same code runs locally, in CI and during
+  wrapper startup.
+- **Fail-fast** — missing logger, missing serviceUrl, missing operations.json:
+  immediate throw.
 
 ## Components
 
-### 1. Mock Infrastructure (Development)
-- `MockMQClient` - In-memory message queue simulation
-- `MockRegistry` - Service registry simulation
-- `MockStorage` - Object storage simulation
+### Mock Infrastructure (for unit tests)
+
+- `MockMQClient` — in-memory message queue simulation
+- `MockRegistry` — service registry simulation
+- `MockStorage` — object storage simulation
 
-### 2. Validation Tools (Production)
-- `ServiceValidator` - OpenAPI compliance and endpoint testing
-- `WorkflowTestRunner` - Cookbook execution testing
-- `CookbookTestUtils` - Cookbook structure validation
+### Production Validation
 
-### 3. Integration Framework
-- `ServiceTestHarness` - Complete test environment orchestration
+- `ValidationOrchestrator` — 6-step pre-validation pipeline, emits proof
+- `ServiceReadinessValidator` — score-based readiness checks (operations /
+  endpoints / health / cookbook / registry)
+- `ServiceStructureValidator` — config layout checks (config/service/*)
+- `ValidationProofGenerator` — fingerprint + codec helpers
+- `CookbookTestRunner` / `WorkflowTestRunner` — cookbook execution probes
+- `CookbookTestUtils` — static cookbook-structure validators
 
-## Use Cases
+### Test Suite Helpers
 
-### Development Workflow
-```javascript
-// Developer testing their service
-const harness = new ServiceTestHarness({
-  service: myExpressApp,
-  serviceName: 'my-service',
-  openApiSpec: spec,
-  mockInfrastructure: true  // Use mocks
-});
+- `createServiceReadinessTests(options)` — Jest suite generator
+- `createPreValidationTests(options)` — Jest suite generator
 
-await harness.start();
-// Run tests...
-await harness.stop();
-```
+## Integration Points
 
-### Production Validation
-```javascript
-// Registry validating new service
-const validator = new ServiceValidator();
-const result = await validator.validateService(
-  serviceUrl,
-  openApiSpec
-);
-
-if (!result.valid) {
-  // Reject registration
-}
-```
-
-### Service-Wrapper Integration
-```javascript
-// Service-wrapper using connector-testing
-class ServiceWrapper {
-  async validateBeforeStart() {
-    const validator = new ServiceValidator();
-    const validation = await validator.validateService(
-      `http://localhost:${this.port}`,
-      this.openApiSpec
-    );
-
-    if (!validation.valid) {
-      throw new Error('Service validation failed');
-    }
-  }
-}
-```
-
-## Testing Strategy
-
-### What We Test
-1. **Service Contract** - OpenAPI compliance
-2. **Workflow Capability** - Can process cookbooks
-3. **Infrastructure Integration** - Registry, MQ, Storage connectivity
-4. **Health & Status** - Monitoring endpoints
-
-### What We DON'T Test
-1. Individual connector functionality (tested in connector packages)
-2. Business logic correctness (service's responsibility)
-3. Performance metrics (separate concern)
-
-## Production Validation Flow
-
-```
-New Service Registration
-         ↓
-    [Registry]
-         ↓
-    Uses connector-testing
-         ↓
-    1. Validate OpenAPI
-    2. Test all endpoints
-    3. Execute test cookbook
-    4. Verify health check
-         ↓
-    Pass? → Accept : Reject
-```
-
-## Integration with Existing System
-
-### Uses Existing Connectors
-- Leverages real connector implementations where possible
-- Only mocks what's necessary for isolation
-- Validates against actual connector interfaces
-
-### Complements Existing Tests
-- Individual connectors have unit tests
-- Services have business logic tests
-- Connector-testing provides integration validation
-
-## Future Enhancements
-
-1. **Performance Benchmarking** - Baseline performance requirements
-2. **Security Validation** - Authentication/authorization checks
-3. **Chaos Testing** - Fault injection and recovery
-4. **Compliance Checking** - Regulatory requirement validation
+- `@onlineapps/service-wrapper` instantiates `ValidationOrchestrator` during
+  wrapper startup. Proof is cached under `conn-runtime/validation-proof.json`
+  (30-day validity, invalidated by config fingerprint change — includes
+  operations map, see
+  [operations-registry-contract.md §3](../../../docs/standards/operations-registry-contract.md)).
+- Biz-service templates import `createPreValidationTests` /
+  `createServiceReadinessTests` from this package for their own test suites.
+
+## What We Test
+
+1. **Service contract** — operations.json structure + endpoint reachability
+2. **Workflow capability** — can process cookbooks
+3. **Infrastructure** — registry / MQ / storage connectivity
+4. **Health** — `/health` returns 200
+
+## What We DO NOT Test
+
+1. Individual connector behavior (tested in connector packages)
+2. Business logic correctness (service responsibility)
+3. Performance / load (separate concern)
+
+## Related Documentation
+
+- [operations-registry-contract.md](../../../docs/standards/operations-registry-contract.md) — operations.json schema
+- [validation-probe-contract.md](../../../docs/standards/validation-probe-contract.md) — required `example`/`default` fields for probes
+- [validator.md](../../../docs/architecture/validator.md) — architecture overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "2.0.33",
+  "version": "3.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "scripts": {
@@ -21,7 +21,7 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/service-validator-core": "1.0.12",
+    "@onlineapps/service-validator-core": "1.0.13",
     "@onlineapps/runtime-config": "1.0.2",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",

package/src/ServiceReadinessValidator.js

@@ -1,29 +1,34 @@
 'use strict';
 
-const ServiceValidator = require('./ServiceValidator');
 const CookbookTestUtils = require('./CookbookTestUtils');
-const { resolveHeaders } = require('./utils/resolveHeaders');
 
 /**
- * ServiceReadinessValidator - Orchestrates complete service validation
- * Used by service-wrapper to verify service is ready for production
+ * ServiceReadinessValidator - Orchestrates complete service validation.
  *
- * IMPORTANT: Only supports operations.json format. OpenAPI is deprecated.
+ * Used by service-wrapper to verify a service is ready for production.
+ * Works exclusively against the v3 operations.json contract — operations
+ * are dispatched via the handler registry (RFC §5.3, §5.9), not HTTP
+ * per-operation endpoints. The HTTP loopback check was removed when v3
+ * adopted in-process handler invocation.
+ *
+ * @see /api/docs/architecture/biz-service-invocation-model.md §5.3
+ * @see /api/docs/standards/validation-probe-contract.md
  */
 class ServiceReadinessValidator {
   constructor(options = {}) {
     if (!options.logger || typeof options.logger.warn !== 'function') {
       throw new Error('[ServiceReadinessValidator] Logger is required — Expected object with warn() method');
     }
-    this.validator = new ServiceValidator(options);
     this.logger = options.logger;
 
     // 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.
     this.checks = {
-      operations: { weight: 30, required: true },   // operations.json structure valid
-      endpoints: { weight: 30, required: true },    // all endpoints respond correctly
+      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)
@@ -69,15 +74,8 @@ class ServiceReadinessValidator {
       results.checks.operations = { passed: false, error: 'Missing operations.json' };
     }
 
-    // 2. Test all declared operations endpoints
-    if (operations && results.checks.operations?.passed) {
-      results.checks.endpoints = await this.checkOperationsEndpoints(url, operations);
-      if (results.checks.endpoints.passed) {
-        results.score += this.checks.endpoints.weight;
-      } else if (this.checks.endpoints.required) {
-        results.errors.push('Endpoint validation failed');
-      }
-    }
+    // 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);
@@ -128,14 +126,15 @@ class ServiceReadinessValidator {
   }
 
   /**
-   * Check operations.json compliance
+   * Check operations.json compliance (v3 — handler registry).
+   * Required per operation: description, handler, bundle_scope, input, output.
+   * Forbidden (v2): endpoint, method, path.
    */
   async checkOperationsCompliance(operations) {
     try {
       const errors = [];
       const warnings = [];
 
-      // Validate operations structure
       if (!operations || typeof operations !== 'object') {
         return {
           passed: false,
@@ -151,17 +150,23 @@ class ServiceReadinessValidator {
         };
       }
 
-      // Validate each operation
+      const validScopes = ['platform', 'tenant', 'workspace'];
+      const handlerPattern = /^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
+      const forbiddenV2Fields = ['endpoint', 'method', 'path'];
+
       for (const [name, operation] of Object.entries(operations)) {
-        // Required fields
         if (!operation.description) {
-          errors.push(`Operation '${name}' missing description`);
+          warnings.push(`Operation '${name}' missing description`);
         }
-        if (!operation.endpoint) {
-          errors.push(`Operation '${name}' missing endpoint`);
+        if (!operation.handler) {
+          errors.push(`Operation '${name}' missing handler (v3 — 'handlers/<path>#<export>')`);
+        } else if (!handlerPattern.test(operation.handler)) {
+          errors.push(`Operation '${name}' has invalid handler ref: '${operation.handler}'`);
         }
-        if (!operation.method) {
-          errors.push(`Operation '${name}' missing method`);
+        if (!operation.bundle_scope) {
+          errors.push(`Operation '${name}' missing bundle_scope (platform|tenant|workspace)`);
+        } else if (!validScopes.includes(operation.bundle_scope)) {
+          errors.push(`Operation '${name}' has invalid bundle_scope: '${operation.bundle_scope}'`);
         }
         if (!operation.input) {
           errors.push(`Operation '${name}' missing input schema`);
@@ -170,15 +175,10 @@ class ServiceReadinessValidator {
           errors.push(`Operation '${name}' missing output schema`);
         }
 
-        // Validate method
-        const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
-        if (operation.method && !validMethods.includes(operation.method)) {
-          errors.push(`Operation '${name}' has invalid method: ${operation.method}`);
-        }
-
-        // Validate endpoint format
-        if (operation.endpoint && !operation.endpoint.startsWith('/')) {
-          warnings.push(`Operation '${name}' endpoint should start with /`);
+        for (const forbidden of forbiddenV2Fields) {
+          if (forbidden in operation) {
+            errors.push(`Operation '${name}' has retired v2 field '${forbidden}' — remove per RFC §5.3`);
+          }
         }
       }
 
@@ -196,85 +196,6 @@ class ServiceReadinessValidator {
     }
   }
 
-  /**
-   * Check all operations endpoints respond correctly
-   */
-  async checkOperationsEndpoints(serviceUrl, operations) {
-    const axios = require('axios');
-    const results = {
-      passed: true,
-      total: Object.keys(operations).length,
-      successful: 0,
-      failed: 0,
-      details: []
-    };
-
-    for (const [operationName, operation] of Object.entries(operations)) {
-      try {
-        const endpoint = operation.endpoint;
-        const method = operation.method.toLowerCase();
-        const url = `${serviceUrl}${endpoint}`;
-
-        // Generate test input based on schema
-        const testInput = this.generateTestInput(operation.input);
-        
-        const validationTenantId = process.env.OA_VALIDATION_TENANT_ID;
-        const validationWorkspaceId = process.env.OA_VALIDATION_WORKSPACE_ID;
-        if (!validationTenantId || !validationWorkspaceId) {
-          throw new Error('[ServiceReadinessValidator] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
-        }
-        const headers = {
-          'x-validation-request': 'true',
-          'x-tenant-id': validationTenantId,
-          'x-workspace-id': validationWorkspaceId,
-          ...resolveHeaders(operation.headers)
-        };
-
-        // Make request
-        const response = await axios({
-          method,
-          url,
-          data: method !== 'get' ? testInput : undefined,
-          params: method === 'get' ? testInput : undefined,
-          headers,
-          timeout: 5000,
-          validateStatus: () => true // Accept any status for validation
-        });
-
-        // Check response: 2xx = success, 4xx = endpoint works but rejected test data (valid)
-        // Only 5xx (server error) or connection failure = invalid endpoint
-        const isValid = response.status < 500;
-
-        if (isValid) {
-          results.successful++;
-        } else {
-          results.failed++;
-          results.passed = false;
-        }
-
-        results.details.push({
-          operation: operationName,
-          endpoint,
-          method: method.toUpperCase(),
-          status: response.status,
-          valid: isValid
-        });
-      } catch (error) {
-        results.failed++;
-        results.passed = false;
-        results.details.push({
-          operation: operationName,
-          endpoint: operation.endpoint,
-          method: operation.method,
-          valid: false,
-          error: error.message
-        });
-      }
-    }
-
-    return results;
-  }
-
   /**
    * Check health endpoint
    */
@@ -349,45 +270,6 @@ class ServiceReadinessValidator {
     }
   }
 
-  /**
-   * Generate test input based on operation input schema.
-   *
-   * Resolution order per field: example > default > enum[0]
-   * If none found for a required field, throws with actionable message.
-   *
-   * Contract: every required field in operations.json MUST have 'example' or 'default'.
-   * See: docs/standards/validation-probe-contract.md
-   */
-  generateTestInput(inputSchema) {
-    const testData = {};
-
-    for (const [fieldName, fieldSpec] of Object.entries(inputSchema)) {
-      if (!fieldSpec.required) continue;
-
-      const value = this._resolveTestValue(fieldName, fieldSpec);
-      testData[fieldName] = value;
-    }
-
-    return testData;
-  }
-
-  /**
-   * Resolve a single test value for a required input field.
-   * Throws if no value can be determined — forces service authors to provide examples.
-   * @private
-   */
-  _resolveTestValue(fieldName, fieldSpec) {
-    if (fieldSpec.example !== undefined) return fieldSpec.example;
-    if (fieldSpec.default !== undefined) return fieldSpec.default;
-    if (Array.isArray(fieldSpec.enum) && fieldSpec.enum.length > 0) return fieldSpec.enum[0];
-
-    throw new Error(
-      `[ServiceReadinessValidator] No test value for required field '${fieldName}' ` +
-      `(type: ${fieldSpec.type}) — Add 'example' or 'default' to operations.json input schema. ` +
-      `See: docs/standards/validation-probe-contract.md`
-    );
-  }
-
   /**
    * Get recommendation based on results
    */

package/src/ValidationOrchestrator.js

@@ -329,7 +329,9 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 3: Validate operations compliance
+   * Step 3: Validate operations compliance (v3 — handler registry dispatch).
+   * Required per operation: handler ('handlers/<path>#<export>'), bundle_scope, input, output.
+   * Forbidden (v2): endpoint, method, path.
    */
   async validateOperations() {
     try {
@@ -337,18 +339,21 @@ class ValidationOrchestrator {
       const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
       const errors = [];
 
-      // Validate each operation
+      const validScopes = ['platform', 'tenant', 'workspace'];
+      const handlerPattern = /^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
+      const forbiddenV2Fields = ['endpoint', 'method', 'path'];
+
       for (const [opName, opDef] of Object.entries(operations.operations || {})) {
-        if (!opDef.endpoint) {
-          errors.push(`Operation ${opName}: missing endpoint`);
-        } else if (!opDef.endpoint.startsWith('/')) {
-          errors.push(`Operation ${opName}: endpoint must start with /`);
+        if (!opDef.handler) {
+          errors.push(`Operation ${opName}: missing handler (v3 — 'handlers/<path>#<export>')`);
+        } else if (!handlerPattern.test(opDef.handler)) {
+          errors.push(`Operation ${opName}: invalid handler ref '${opDef.handler}' — expected 'handlers/<path>#<exportName>'`);
         }
 
-        if (!opDef.method) {
-          errors.push(`Operation ${opName}: missing method`);
-        } else if (!['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(opDef.method)) {
-          errors.push(`Operation ${opName}: invalid HTTP method`);
+        if (!opDef.bundle_scope) {
+          errors.push(`Operation ${opName}: missing bundle_scope (platform|tenant|workspace)`);
+        } else if (!validScopes.includes(opDef.bundle_scope)) {
+          errors.push(`Operation ${opName}: invalid bundle_scope '${opDef.bundle_scope}' — expected one of ${validScopes.join(', ')}`);
         }
 
         if (!opDef.input) {
@@ -357,6 +362,12 @@ class ValidationOrchestrator {
         if (!opDef.output) {
           errors.push(`Operation ${opName}: missing output schema`);
         }
+
+        for (const forbidden of forbiddenV2Fields) {
+          if (forbidden in opDef) {
+            errors.push(`Operation ${opName}: retired v2 field '${forbidden}' present — remove per RFC §5.3`);
+          }
+        }
       }
 
       console.log(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`);
@@ -374,6 +385,11 @@ class ValidationOrchestrator {
 
   /**
    * Step 4: Run cookbook tests
+   *
+   * v3 note: per-operation HTTP dispatch is retired. If operations.json is v3
+   * (schema_version "3.0" or any operation declares `handler`), cookbook runs
+   * are skipped here with a warning. Handler-registry-based cookbook dispatch
+   * is tracked separately (see RFC §5.3, §5.9).
    */
   async runCookbookTests() {
     try {
@@ -390,6 +406,25 @@ class ValidationOrchestrator {
         };
       }
 
+      const operationsFile = path.join(this.configPath, 'operations.json');
+      let isV3 = false;
+      try {
+        const ops = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
+        const opValues = Object.values(ops.operations || {});
+        isV3 = ops.schema_version === '3.0' || opValues.some(o => o && typeof o === 'object' && 'handler' in o);
+      } catch (_) { /* fall through to runner */ }
+
+      if (isV3) {
+        console.warn('[ValidationOrchestrator] Step 4: cookbook HTTP dispatch is v2-only. Skipping for v3 ops schema.');
+        return {
+          success: true,
+          total: 0,
+          passed: 0,
+          failed: 0,
+          warnings: ['Cookbook tests skipped — v3 handler-registry dispatch not yet implemented in CookbookTestRunner']
+        };
+      }
+
       const result = await this.cookbookRunner.runCookbooks(cookbooksPath);
 
       console.log(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);

package/src/config.js

@@ -4,7 +4,7 @@
  * Runtime configuration schema for @onlineapps/conn-orch-validator.
  *
  * Uses @onlineapps/runtime-config for unified priority:
- * 1. Explicit config (passed to TestOrchestrator options)
+ * 1. Explicit config (passed to ValidationOrchestrator/readiness options)
  * 2. Environment variable
  * 3. Module-owned defaults (none for topology)
  *

package/src/helpers/createServiceReadinessTests.js

@@ -179,14 +179,12 @@ function createServiceReadinessTests(testsDir, options = {}) {
         expect(result.score).toBe(100);
         expect(result.checks.health?.passed).toBe(true);
         expect(result.checks.operations?.passed).toBe(true);
-        expect(result.checks.endpoints?.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);
-        expect(result.checks.endpoints?.passed).toBe(true);
       }
     }, timeout);
 
@@ -199,7 +197,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
       expect(data.status).toBe('healthy');
     });
 
-    test('service has valid operations specification', () => {
+    test('service has valid operations specification (v3)', () => {
       expect(operations).toBeDefined();
       expect(operations.operations || operations).toBeDefined();
 
@@ -207,12 +205,16 @@ function createServiceReadinessTests(testsDir, options = {}) {
       expect(typeof operationsFlat).toBe('object');
       expect(Object.keys(operationsFlat).length).toBeGreaterThan(0);
 
-      // Verify operations structure
-      for (const [operationName, operationSpec] of Object.entries(operationsFlat)) {
-        expect(operationSpec).toHaveProperty('endpoint');
-        expect(operationSpec).toHaveProperty('method');
-        expect(operationSpec.endpoint).toMatch(/^\//);
-        expect(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).toContain(operationSpec.method);
+      const validScopes = ['platform', 'tenant', 'workspace'];
+      const handlerPattern = /^handlers\/[a-zA-Z0-9_/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+      for (const [, operationSpec] of Object.entries(operationsFlat)) {
+        expect(operationSpec).toHaveProperty('handler');
+        expect(operationSpec).toHaveProperty('bundle_scope');
+        expect(operationSpec.handler).toMatch(handlerPattern);
+        expect(validScopes).toContain(operationSpec.bundle_scope);
+        expect(operationSpec).not.toHaveProperty('endpoint');
+        expect(operationSpec).not.toHaveProperty('method');
       }
     });
   });