@onlineapps/conn-orch-validator 5.0.0 → 6.0.0

package/README.md

@@ -94,7 +94,7 @@ legitimate state until every repo adopts the declaration, and never silent.
 
 ```
 services/my-service/
-├── conn-config/              ← Static (gitignored: NO)
+├── config/service/              ← Static (gitignored: NO)
 │   ├── config.json
 │   └── operations.json
 ├── conn-runtime/             ← Runtime (gitignored: YES)
@@ -140,7 +140,7 @@ The validator evaluates each service against cumulative implementation standards
 
 | Level | Name | Checks | Since |
 |-------|------|--------|-------|
-| **v1.0** | Base Service Standard | `conn-config/`, `src/app.js`, `index.js`, valid `config.json` + `operations.json`, `@onlineapps/service-wrapper` dep | 2025-06 |
+| **v1.0** | Base Service Standard | `config/service/`, `src/app.js`, `index.js`, valid `config.json` + `operations.json`, `@onlineapps/service-wrapper` dep | 2025-06 |
 | **v1.1** | Multitenancy Standard | `wrapper.tenantContext` configured in `config.json` | 2026-03 |
 | **v1.2** | Business Error Handling | `business_error_contract` (some file under `src/**` imports a `BusinessError` family from `@onlineapps/service-wrapper` or declares the brand `onlineapps.businessError`) + `no_retired_error_hierarchy` (no error class imported from `@onlineapps/service-common` anywhere under `src/`) | 2026-03 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "bin": {
@@ -9,7 +9,6 @@
   "scripts": {
     "test": "jest",
     "test:unit": "jest tests/unit",
-    "test:component": "jest tests/component",
     "test:integration": "jest tests/integration",
     "test:coverage": "jest --coverage"
   },

package/src/CookbookTestRunner.js

@@ -10,6 +10,10 @@ const { checkCookbookFormatVersion, normalizeCookbookSteps } = require('./utils/
 const { getTestNamespace } = require('./utils/testNamespace');
 const { describeStepFailure, describeStepIdentity } = require('./utils/stepFailure');
 
+// The logger methods this runner requires — the order is the order the error
+// message lists them in.
+const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+
 /**
  * The step's stopwatch, spelled out. A single total hid the fact that
  * biz-hello's `count_stub` spent 2264 ms loading sequelize and ~0 ms doing its
@@ -37,7 +41,7 @@ function describeStepTiming(result) {
  *     httpClient: null, secrets: null, state: null, stream: null,
  *     abortSignal: null }
  * matching the shape ServiceWrapper.ContextBuilder produces in production
- * (see api/docs/architecture/biz-service-invocation-model.md §5). Handlers
+ * (see api/docs/biz/10-invocation/handler-dispatch.md). Handlers
  * that need DB access import sequelize directly from their own
  * src/config/database.js module (see biz/60-templates/onboarding-checklist.md §9a);
  * connector slots stay null and the handler surfaces its own failure if
@@ -50,8 +54,29 @@ class CookbookTestRunner {
     if (!options.serviceName) {
       throw new Error('[CookbookTestRunner] serviceName is required');
     }
-    if (!options.logger || typeof options.logger.warn !== 'function') {
-      throw new Error('[CookbookTestRunner] Logger is required — Expected object with warn() method');
+    // The logger is INJECTED and validated in full, HERE. Until 2026-09-03 only
+    // `warn()` was checked — the one method this runner never calls, while it
+    // calls info() and error() throughout a run. A logger without them therefore
+    // constructed fine and died on the first log line: delayed validation, which
+    // architecture-principles.md §4 forbids. Owner confirmation:
+    // docs/governance/confirmations/connector-logger-contract.md 001.
+    if (!options.logger) {
+      throw new Error(
+        '[CookbookTestRunner] Logger is required - Expected: a logger with info/warn/error/debug, '
+        + 'so the runner writes where the service writes. '
+        + 'Fix: pass options.logger (e.g. the logger your service already built).'
+      );
+    }
+
+    const missingLoggerMethods = LOGGER_METHODS.filter(
+      (method) => typeof options.logger[method] !== 'function'
+    );
+    if (missingLoggerMethods.length > 0) {
+      throw new Error(
+        '[CookbookTestRunner] Logger is incomplete - Expected: info, warn, error, debug as functions; '
+        + `missing: ${missingLoggerMethods.join(', ')}. `
+        + 'Fix: pass a logger implementing all four.'
+      );
     }
     this.serviceName = options.serviceName;
     this.servicePath = options.servicePath;
@@ -310,7 +335,7 @@ class CookbookTestRunner {
   /**
    * Handler dispatch: require handler module, build minimal real ctx, call
    * handler(input, ctx). Mirrors the production ContextBuilder shape
-   * (see api/docs/architecture/biz-service-invocation-model.md §5) with
+   * (see api/docs/biz/10-invocation/handler-dispatch.md) with
    * all connector slots set to null — handlers that need DB access use
    * direct sequelize import per biz/60-templates/onboarding-checklist.md §9a.
    */
@@ -621,12 +646,12 @@ class CookbookTestRunner {
    */
   async resolveOperation(serviceName, operationName) {
     const serviceRoot = this._resolveServiceRoot(serviceName);
-    const newPath = path.join(serviceRoot, 'config', 'service', 'operations.json');
-    const legacyPath = path.join(serviceRoot, 'conn-config', 'operations.json');
-    const operationsPath = fs.existsSync(newPath) ? newPath : (fs.existsSync(legacyPath) ? legacyPath : null);
+    // config/service/ is the ONLY configuration path (owner decision
+    // 2026-09-03) — the legacy conn-config/ layout exists in no repository.
+    const operationsPath = path.join(serviceRoot, 'config', 'service', 'operations.json');
 
-    if (!operationsPath) {
-      throw new Error(`Operations file not found for service: ${serviceName} (checked config/service/ and conn-config/)`);
+    if (!fs.existsSync(operationsPath)) {
+      throw new Error(`Operations file not found for service: ${serviceName} (expected config/service/operations.json)`);
     }
 
     const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf8'));

package/src/ServiceReadinessValidator.js

@@ -2,6 +2,10 @@
 
 const CookbookTestUtils = require('./CookbookTestUtils');
 
+// The logger methods this validator requires — the order is the order the
+// error message lists them in.
+const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+
 /**
  * ServiceReadinessValidator - Orchestrates complete service validation.
  *
@@ -32,15 +36,37 @@ const CookbookTestUtils = require('./CookbookTestUtils');
  * `tests/bootstrap/` suites of the biz repos — which pass name, version,
  * operations, testCookbook and registry, and never passed a url.
  *
- * @see /api/docs/architecture/biz-service-invocation-model.md §5.3
+ * @see api/docs/biz/30-operations/schema-v3.md
  * @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 = {}) {
-    if (!options.logger || typeof options.logger.warn !== 'function') {
-      throw new Error('[ServiceReadinessValidator] Logger is required — Expected object with warn() method');
+    // The logger is INJECTED and validated in full, HERE — and, since
+    // 2026-09-03, actually used: validateReadiness() writes the verdict through
+    // it. Until then this class demanded a logger and never wrote a line, so a
+    // caller that did not print the returned object learned nothing about why a
+    // service was refused. Owner confirmation:
+    // docs/governance/confirmations/connector-logger-contract.md 001.
+    if (!options.logger) {
+      throw new Error(
+        '[ServiceReadinessValidator] Logger is required - Expected: a logger with info/warn/error/debug, '
+        + 'so the readiness verdict leaves the process. '
+        + 'Fix: pass options.logger (e.g. the logger your service already built).'
+      );
     }
+
+    const missingLoggerMethods = LOGGER_METHODS.filter(
+      (method) => typeof options.logger[method] !== 'function'
+    );
+    if (missingLoggerMethods.length > 0) {
+      throw new Error(
+        '[ServiceReadinessValidator] Logger is incomplete - Expected: info, warn, error, debug as functions; '
+        + `missing: ${missingLoggerMethods.join(', ')}. `
+        + 'Fix: pass a logger implementing all four.'
+      );
+    }
+
     this.logger = options.logger;
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
@@ -149,6 +175,42 @@ class ServiceReadinessValidator {
     results.ready = requiredPassed && results.score >= 60;
     results.recommendation = this.getRecommendation(results);
 
+    // ONE line per evaluation, carrying the whole verdict as a structured
+    // object: what was checked, what each check contributed, and why the answer
+    // is what it is. Per check there is nothing — a line per check says the same
+    // thing in more places, and this runs on every biz service boot.
+    //
+    // `score` is read off the check rather than assumed: a check that never
+    // reached award() (operations absent entirely) carries no score field, and
+    // the log says 0 instead of `undefined`.
+    const checkSummary = {};
+    for (const [name, check] of Object.entries(results.checks)) {
+      checkSummary[name] = {
+        passed: check.passed === true,
+        score: typeof check.score === 'number' ? check.score : 0
+      };
+    }
+
+    this.logger.info('[ServiceReadinessValidator] Readiness evaluated', {
+      serviceName: results.serviceName,
+      score: results.score,
+      maxScore: results.maxScore,
+      ready: results.ready,
+      checks: checkSummary,
+      errors: results.errors,
+      warnings: results.warnings
+    });
+
+    // A refusal is an error-level event wherever logs are filtered by level;
+    // the info line above still carries the detail.
+    if (results.ready === false) {
+      this.logger.error('[ServiceReadinessValidator] Service not ready', {
+        serviceName: results.serviceName,
+        score: results.score,
+        errors: results.errors
+      });
+    }
+
     return results;
   }
 

package/src/ValidationOrchestrator.js

@@ -10,6 +10,10 @@ const { ServiceStructureValidator } = require('./validators/ServiceStructureVali
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
 const CookbookTestRunner = require('./CookbookTestRunner');
 
+// The logger methods this orchestrator requires — the order is the order the
+// error message lists them in.
+const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+
 /**
  * ValidationOrchestrator
  *
@@ -36,15 +40,39 @@ class ValidationOrchestrator {
     this.serviceRoot = options.serviceRoot;
     this.serviceName = options.serviceName;
     this.serviceVersion = options.serviceVersion;
-    if (!options.logger || typeof options.logger.warn !== 'function') {
-      throw new Error('[ValidationOrchestrator] Logger is required — Expected object with warn() method');
+    // The logger is INJECTED and validated in full, HERE. Until 2026-09-03 only
+    // `warn()` was checked, while this class narrates every step of a run and
+    // hands the same object to CookbookTestRunner below, which demands all four.
+    // An incomplete logger therefore reached the runner one line later and threw
+    // in its name instead of this one. Owner confirmation:
+    // docs/governance/confirmations/connector-logger-contract.md 001.
+    if (!options.logger) {
+      throw new Error(
+        '[ValidationOrchestrator] Logger is required - Expected: a logger with info/warn/error/debug, '
+        + 'so validation narrates where the service writes. '
+        + 'Fix: pass options.logger (e.g. the logger your service already built).'
+      );
+    }
+
+    const missingLoggerMethods = LOGGER_METHODS.filter(
+      (method) => typeof options.logger[method] !== 'function'
+    );
+    if (missingLoggerMethods.length > 0) {
+      throw new Error(
+        '[ValidationOrchestrator] Logger is incomplete - Expected: info, warn, error, debug as functions; '
+        + `missing: ${missingLoggerMethods.join(', ')}. `
+        + 'Fix: pass a logger implementing all four.'
+      );
     }
+
     this.logger = options.logger;
 
-    // Paths — prefer new config/service/ layout, fall back to legacy conn-config/
-    const newConfigDir = path.join(this.serviceRoot, 'config', 'service');
-    const legacyConfigDir = path.join(this.serviceRoot, 'conn-config');
-    this.configPath = fs.existsSync(newConfigDir) ? newConfigDir : legacyConfigDir;
+    // config/service/ is the ONLY configuration path (owner decision
+    // 2026-09-03). The legacy conn-config/ branch is gone: zero such
+    // directories existed across api_biz/* and infra/* when it was removed, so
+    // it could only ever resolve to a path that does not exist and report the
+    // failure one layer away from the cause.
+    this.configPath = path.join(this.serviceRoot, 'config', 'service');
 
     this.runtimePath = path.join(this.serviceRoot, 'conn-runtime');
     this.proofPath = path.join(this.runtimePath, 'validation-proof.json');
@@ -64,7 +92,7 @@ class ValidationOrchestrator {
    * Checks if proof exists and is valid, or runs full validation
    */
   async validate() {
-    console.log('[ValidationOrchestrator] Starting validation...');
+    this.logger.info('[ValidationOrchestrator] Starting validation...');
 
     // Check if proof exists and is valid
     // No proof cache. It skipped steps 1-3 and 5-6 — measured at 6 ms in total
@@ -79,9 +107,9 @@ class ValidationOrchestrator {
     // Dockerfile either. Removing it gives up no capability.
     //
     // Its original justification — an HTTP probe with retries in step 5 — was
-    // removed in 3.3.1 under ADR 0005. Audit: docs/archive/validation-proof-audit-2026-08.md
+    // removed in 3.3.1 under ADR 0005.
     // Run full validation
-    console.log('[ValidationOrchestrator] No valid proof, running validation...');
+    this.logger.info('[ValidationOrchestrator] No valid proof, running validation...');
     return await this.runFullValidation();
   }
 
@@ -223,7 +251,7 @@ class ValidationOrchestrator {
 
     try {
       // Step 1: Service Structure
-      console.log('[ValidationOrchestrator] Step 1/6: Service Structure');
+      this.logger.info('[ValidationOrchestrator] Step 1/6: Service Structure');
       results.steps.structure = await this.validateStructure();
       if (!results.steps.structure.valid) {
         results.success = false;
@@ -233,7 +261,7 @@ class ValidationOrchestrator {
       }
 
       // Step 2: Config Files
-      console.log('[ValidationOrchestrator] Step 2/6: Config Files');
+      this.logger.info('[ValidationOrchestrator] Step 2/6: Config Files');
       results.steps.config = await this.validateConfig();
       if (!results.steps.config.valid) {
         results.success = false;
@@ -247,7 +275,7 @@ class ValidationOrchestrator {
       // start without must fail here, where its name and the reason it exists
       // are both at hand. SECRETS_MASTER_KEY used to fail after MQ
       // registration, several layers away from the declaration (defect D2).
-      console.log('[ValidationOrchestrator] Step 3/6: Environment Contract');
+      this.logger.info('[ValidationOrchestrator] Step 3/6: Environment Contract');
       results.steps.env = this.validateEnvContract();
       if (!results.steps.env.valid) {
         results.success = false;
@@ -258,7 +286,7 @@ class ValidationOrchestrator {
       }
 
       // Step 4: Operations Compliance
-      console.log('[ValidationOrchestrator] Step 4/6: Operations Compliance');
+      this.logger.info('[ValidationOrchestrator] Step 4/6: Operations Compliance');
       results.steps.operations = await this.validateOperations();
       results.warnings.push(...(results.steps.operations.warnings || []));
       if (!results.steps.operations.valid) {
@@ -267,7 +295,7 @@ class ValidationOrchestrator {
       }
 
       // Step 5: Cookbook Tests
-      console.log('[ValidationOrchestrator] Step 5/6: Cookbook Tests');
+      this.logger.info('[ValidationOrchestrator] Step 5/6: Cookbook Tests');
       results.steps.cookbooks = await this.runCookbookTests();
       results.totalTests += results.steps.cookbooks.total || 0;
       results.passedTests += results.steps.cookbooks.passed || 0;
@@ -278,7 +306,7 @@ class ValidationOrchestrator {
       }
 
       // Step 6: Connector Integration
-      console.log('[ValidationOrchestrator] Step 6/6: Connector Integration');
+      this.logger.info('[ValidationOrchestrator] Step 6/6: Connector Integration');
       results.steps.connectors = this.validateConnectors();
       if (!results.steps.connectors.valid) {
         // Severity is unchanged: the connector contract stays non-critical and
@@ -298,7 +326,7 @@ class ValidationOrchestrator {
       return await this.finalizeResults(results, startTime);
 
     } catch (error) {
-      console.error(`[ValidationOrchestrator] Validation failed: ${error.message}`);
+      this.logger.error(`[ValidationOrchestrator] Validation failed: ${error.message}`);
       results.success = false;
       results.errors.push(`Validation error: ${error.message}`);
       return this.finalizeResults(results, startTime);
@@ -312,7 +340,7 @@ class ValidationOrchestrator {
     try {
       const result = this.structureValidator.validate();
 
-      console.log(`[ValidationOrchestrator] ✓ Service structure: ${result.valid ? 'PASS' : 'FAIL'}`);
+      this.logger.info(`[ValidationOrchestrator] ✓ Service structure: ${result.valid ? 'PASS' : 'FAIL'}`);
       return result;
     } catch (error) {
       return {
@@ -350,7 +378,7 @@ class ValidationOrchestrator {
         }
       }
 
-      console.log(`[ValidationOrchestrator] ✓ Config files: ${errors.length === 0 ? 'PASS' : 'FAIL'}`);
+      this.logger.info(`[ValidationOrchestrator] ✓ Config files: ${errors.length === 0 ? 'PASS' : 'FAIL'}`);
       return {
         valid: errors.length === 0,
         errors: errors
@@ -413,7 +441,7 @@ class ValidationOrchestrator {
         }
       }
 
-      console.log(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`
+      this.logger.info(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`
         + `${warnings.length > 0 ? ` (${warnings.length} warning(s))` : ''}`);
       return {
         valid: errors.length === 0,
@@ -440,7 +468,7 @@ class ValidationOrchestrator {
       const cookbooksPath = path.join(this.serviceRoot, 'tests', 'cookbooks');
 
       if (!fs.existsSync(cookbooksPath)) {
-        console.warn('[ValidationOrchestrator] No cookbook tests found (tests/cookbooks/ missing)');
+        this.logger.warn('[ValidationOrchestrator] No cookbook tests found (tests/cookbooks/ missing)');
         return {
           success: true,
           total: 0,
@@ -452,7 +480,7 @@ class ValidationOrchestrator {
 
       const result = await this.cookbookRunner.runCookbooks(cookbooksPath);
 
-      console.log(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);
+      this.logger.info(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);
 
       // `N cookbook test(s) failed` was the whole error list until 2026-08-29:
       // the count without a single name, so `Validation failed: 1 cookbook
@@ -462,7 +490,7 @@ class ValidationOrchestrator {
       const failedSteps = (result.steps || []).filter((step) => step.passed === false);
       const details = failedSteps.map(describeStepFailureWithContext);
       for (const detail of details) {
-        console.error(`[ValidationOrchestrator]   ✗ ${detail}`);
+        this.logger.error(`[ValidationOrchestrator]   ✗ ${detail}`);
       }
 
       return {
@@ -517,7 +545,7 @@ class ValidationOrchestrator {
       // connector step; what is new here is a declaration that exists and is
       // wrong, and that must stop the boot rather than be worked around.
       if (error.code === 'ENOENT') {
-        console.log('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
+        this.logger.info('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
           + `no ${path.relative(this.serviceRoot, contractFile)} in this service`);
         return { valid: true, skipped: true, errors: [] };
       }
@@ -525,14 +553,14 @@ class ValidationOrchestrator {
     }
 
     if (declaration === null) {
-      console.log('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
+      this.logger.info('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
         + 'config/service/integration-contract.json declares no "env" block '
         + '(F16 adoption pending; nothing is being checked here)');
       return { valid: true, skipped: true, errors: [] };
     }
 
     const result = verifyEnvPresence({ declaration, env: process.env });
-    console.log(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Environment contract: `
+    this.logger.info(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Environment contract: `
       + `${result.valid ? 'PASS' : 'FAIL'} (${result.checked.length} required name(s) checked: `
       + `${result.checked.join(', ') || 'none'})`);
     return { valid: result.valid, errors: result.errors };
@@ -561,7 +589,7 @@ class ValidationOrchestrator {
     }
 
     const result = verifyConnectorContract({ config, requiredConnectors, env: process.env });
-    console.log(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Connector contract: `
+    this.logger.info(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Connector contract: `
       + `${result.valid ? 'PASS' : 'FAIL'} (${result.checked.length} checked: ${result.checked.join(', ') || 'none'})`);
     return { valid: result.valid, errors: result.errors };
   }
@@ -599,20 +627,20 @@ class ValidationOrchestrator {
         results.proof = encodedProof;
         results.fingerprint = fingerprint;
 
-        console.log(`[ValidationOrchestrator] ✅ Validation PASSED (${duration}ms)`);
-        console.log(`[ValidationOrchestrator] Proof saved to: ${this.proofPath}`);
+        this.logger.info(`[ValidationOrchestrator] ✅ Validation PASSED (${duration}ms)`);
+        this.logger.info(`[ValidationOrchestrator] Proof saved to: ${this.proofPath}`);
       } catch (error) {
-        console.error(`[ValidationOrchestrator] Failed to generate proof: ${error.message}`);
+        this.logger.error(`[ValidationOrchestrator] Failed to generate proof: ${error.message}`);
         results.success = false;
         results.errors.push(`Proof generation failed: ${error.message}`);
       }
     } else {
-      console.error(`[ValidationOrchestrator] ❌ Validation FAILED (${duration}ms)`);
+      this.logger.error(`[ValidationOrchestrator] ❌ Validation FAILED (${duration}ms)`);
       // The trailing `(', ')}` was a leftover from a half-finished edit to a
       // template literal: it printed on every failed validation as if it were
       // part of the data. Found while reading this line for the biz-hello
       // diagnosis (2026-08-29).
-      console.error(`[ValidationOrchestrator] Errors: ${JSON.stringify(results.errors, null, 2)}`);
+      this.logger.error(`[ValidationOrchestrator] Errors: ${JSON.stringify(results.errors, null, 2)}`);
     }
 
     return results;
@@ -635,7 +663,7 @@ class ValidationOrchestrator {
       // Save proof
       fs.writeFileSync(this.proofPath, JSON.stringify(proof, null, 2));
 
-      console.log(`[ValidationOrchestrator] Proof saved: ${this.proofPath}`);
+      this.logger.info(`[ValidationOrchestrator] Proof saved: ${this.proofPath}`);
     } catch (error) {
       throw new Error(`Failed to save proof: ${error.message}`);
     }

package/src/WorkflowTestRunner.js

@@ -150,7 +150,13 @@ class WorkflowTestRunner extends EventEmitter {
     const resolvedInput = this.resolveInput(input, workflow.context);
     
     if (this.debug) {
-      console.log(`Executing task: ${service}.${operation}`, resolvedInput);
+      // WHICH operation ran, never WHAT it carried: the resolved input is the
+      // workflow's payload, and printing it to stdout put whatever the cookbook
+      // held — identifiers, amounts, anything — into the terminal and every log
+      // collector behind it. This class takes no logger (constructor above), so
+      // the trace stays on console; giving it one is an API change and the
+      // owner's call, not a side effect of this fix.
+      console.log(`Executing task: ${service}.${operation}`);
     }
 
     // Get service from registry

package/src/helpers/README.md

@@ -20,7 +20,7 @@ Instead of **copying test code** between services, we provide **reusable test he
 **File:** `createServiceReadinessTests.js`
 
 **What it does:**
-- Validates service structure (conn-config/, src/app.js, package.json)
+- Validates service structure (config/service/, src/handlers/, package.json)
 - Validates configuration files (config.json, operations.json)
 - Tests all operations endpoints
 - Validates health endpoint
@@ -70,7 +70,7 @@ The helper uses `ServiceStructureValidator` to validate service structure BEFORE
 
 ✅ ALL CHECKS PASSED
 
-   ✓ Found Configuration directory: conn-config
+   ✓ Found Configuration directory: config/service
    ✓ Found Source code directory: src
    ✓ Found Tests directory: tests
    ✓ Found valid config.json
@@ -86,14 +86,14 @@ If validation fails, clear error messages are shown:
 ```
 ❌ ERRORS (2):
 
-   ✗ Required directory missing: conn-config
+   ✗ Required directory missing: config/service/
      Type: MISSING_DIRECTORY
-     File: conn-config
-     Fix: Create directory: mkdir -p conn-config
+     File: config/service/
+     Fix: Create directory: mkdir -p config/service
 
-   ✗ Service configuration missing: conn-config/config.json
+   ✗ Service configuration missing: config/service/config.json
      Type: MISSING_CONFIG
-     File: conn-config/config.json
+     File: config/service/config.json
      Fix: Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md
 
 ⚠️  WARNINGS (1):
@@ -111,8 +111,8 @@ The helper automatically detects and loads:
 const serviceRoot = path.resolve(__dirname, '../..');
 
 // Standard file locations
-const config = require(path.join(serviceRoot, 'conn-config/config.json'));
-const operations = require(path.join(serviceRoot, 'conn-config/operations.json'));
+const config = require(path.join(serviceRoot, 'config/service/config.json'));
+const operations = require(path.join(serviceRoot, 'config/service/operations.json'));
 const app = require(path.join(serviceRoot, 'src/app.js'));
 
 // Extract metadata
@@ -157,7 +157,7 @@ function createMyTests(testsDir, options = {}) {
   }
 
   // 2. Load config
-  const config = require(path.join(serviceRoot, 'conn-config/config.json'));
+  const config = require(path.join(serviceRoot, 'config/service/config.json'));
 
   // 3. Create test suite
   describe('My Test Suite @integration', () => {

package/src/helpers/createServiceReadinessTests.js

@@ -40,6 +40,10 @@ const { MIN_COOKBOOK_FORMAT_VERSION } = require('../utils/cookbookFormat');
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.includeOptionalChecks=true] - Include cookbook & registry checks
  * @param {number} [options.timeout=15000] - Test timeout in ms
+ * @param {Object} [options.logger=console] - Logger handed to
+ *   ServiceReadinessValidator (info/warn/error/debug). Defaults to `console`,
+ *   which is the report channel of a jest bootstrap suite — see the comment at
+ *   the call site and FALLBACKS_INVENTORY.md §5.6.
  *
  * @example
  * // In services/my-service/tests/bootstrap/service-readiness.test.js
@@ -71,14 +75,11 @@ function createServiceReadinessTests(testsDir, options = {}) {
     );
   }
 
-  // Load configuration files — prefer config/service/, fall back to conn-config/
-  const resolveConfig = (filename) => {
-    const newPath = path.join(serviceRoot, 'config', 'service', filename);
-    const legacyPath = path.join(serviceRoot, 'conn-config', filename);
-    return fs.existsSync(newPath) ? newPath : legacyPath;
-  };
-  const configPath = resolveConfig('config.json');
-  const operationsPath = resolveConfig('operations.json');
+  // config/service/ is the ONLY configuration path (owner decision 2026-09-03).
+  // The legacy conn-config/ branch is gone — it existed in no repository, so it
+  // could only turn a missing file into a read error naming a retired layout.
+  const configPath = path.join(serviceRoot, 'config', 'service', 'config.json');
+  const operationsPath = path.join(serviceRoot, 'config', 'service', 'operations.json');
 
   const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
@@ -113,7 +114,15 @@ function createServiceReadinessTests(testsDir, options = {}) {
         };
       }
 
-      const validator = new ServiceReadinessValidator({ logger: console });
+      // `console` is the intended logger here, not a stand-in for one that is
+      // unavailable: this helper builds a jest suite in a service's
+      // tests/bootstrap, where stdout IS the report the developer reads, and
+      // every one of the eight biz services calls it as
+      // `createServiceReadinessTests(__dirname)` from its own repository.
+      // A caller that has a real logger passes one; nobody is forced to invent
+      // one to run their tests.
+      // @see api/docs/standards/FALLBACKS_INVENTORY.md §5.6
+      const validator = new ServiceReadinessValidator({ logger: options.logger ?? console });
       const result = await validator.validateReadiness({
         name: serviceName,
         version: serviceVersion,

package/src/index.js

@@ -20,12 +20,13 @@ const CookbookTestUtils = require('./CookbookTestUtils');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
 
-let CookbookTestRunner;
-try {
-  CookbookTestRunner = require('./CookbookTestRunner');
-} catch (error) {
-  console.error('[conn-orch-validator] WARNING: Failed to load CookbookTestRunner:', error.message);
-}
+// Required like every other export: a broken require fails the load, here,
+// with its own stack. The try/catch that used to guard it printed a WARNING and
+// left `CookbookTestRunner: undefined` on the exports — a fallback (§3) and
+// delayed validation (§4) that could not even do what it promised, since
+// ./ValidationOrchestrator below requires the same module unguarded and took
+// the load down anyway. All it added was a misleading line before the real one.
+const CookbookTestRunner = require('./CookbookTestRunner');
 const WorkflowTestRunner = require('./WorkflowTestRunner');
 const BizCiGateContract = require('./utils/bizCiGateContract');
 

package/src/validators/ServiceStructureValidator.js

@@ -16,25 +16,26 @@ const fs = require('fs');
 const path = require('path');
 
 /**
- * Try reading from new path first (config/service/), fall back to legacy (conn-config/).
+ * Read a configuration file from the ONE place a service may keep it:
+ * `config/service/`. The legacy `conn-config/` alternative was removed on
+ * 2026-09-03 (owner decision) — no repository carried such a directory any
+ * more, so accepting it only taught a shape nobody may build and let every
+ * finding offer a fix pointing at a retired layout.
+ *
  * @param {string} root - Service root
  * @param {string} filename - e.g. 'config.json'
  * @returns {string|null} File contents or null
  */
 function readConfigFile(root, filename) {
-  const candidates = [
-    path.join(root, 'config', 'service', filename),
-    path.join(root, 'conn-config', filename)
-  ];
-  for (const p of candidates) {
-    try { return fs.readFileSync(p, 'utf-8'); } catch { /* try next */ }
+  try {
+    return fs.readFileSync(path.join(root, 'config', 'service', filename), 'utf-8');
+  } catch {
+    return null;
   }
-  return null;
 }
 
 function hasConfigDir(root) {
-  return fs.existsSync(path.join(root, 'config', 'service')) ||
-         fs.existsSync(path.join(root, 'conn-config'));
+  return fs.existsSync(path.join(root, 'config', 'service'));
 }
 
 
@@ -225,7 +226,7 @@ const STANDARD_LEVELS = [
       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; } };
 
-      results.push({ passed: hasConfigDir(root), id: 'dir_conn_config', message: 'config/service/ or conn-config/ directory' });
+      results.push({ passed: hasConfigDir(root), id: 'dir_config_service', message: 'config/service/ directory' });
       results.push({ passed: has('src'), id: 'dir_src', message: 'src/ directory' });
       results.push({ passed: has('tests'), id: 'dir_tests', message: 'tests/ directory' });
       // ADR 0005: src/handlers/ replaces src/app.js. Flat handlers/ or
@@ -449,8 +450,8 @@ class ServiceStructureValidator {
     if (!hasConfigDir(this.serviceRoot)) {
       this.errors.push({
         type: 'MISSING_DIRECTORY',
-        path: 'config/service/ (or conn-config/)',
-        message: 'Required directory missing: config/service/ (or legacy conn-config/)',
+        path: 'config/service/',
+        message: 'Required directory missing: config/service/',
         description: 'Configuration directory',
         fix: 'Create directory: mkdir -p config/service'
       });
@@ -501,8 +502,8 @@ class ServiceStructureValidator {
     if (!configRaw) {
       this.errors.push({
         type: 'MISSING_CONFIG',
-        path: 'config/service/config.json (or conn-config/config.json)',
-        message: 'Service configuration missing: config/service/config.json (or conn-config/config.json)',
+        path: 'config/service/config.json',
+        message: 'Service configuration missing: config/service/config.json',
         fix: 'Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md'
       });
     } else {
@@ -524,8 +525,8 @@ class ServiceStructureValidator {
     if (!opsRaw) {
       this.errors.push({
         type: 'MISSING_OPERATIONS',
-        path: 'config/service/operations.json (or conn-config/operations.json)',
-        message: 'Operations specification missing: config/service/operations.json (or conn-config/operations.json)',
+        path: 'config/service/operations.json',
+        message: 'Operations specification missing: config/service/operations.json',
         fix: 'Create operations.json. See: /docs/biz/30-operations/schema-v3.md'
       });
     } else {