@onlineapps/conn-orch-validator 3.2.3 → 3.3.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog — @onlineapps/conn-orch-validator
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [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`.
+
+### BREAKING
+
+- **`CookbookTestRunner._dispatchViaHandler`** now reads `TESTING_TENANT_ID` and `TESTING_WORKSPACE_ID` from `process.env`. Old names `OA_VALIDATION_TENANT_ID` / `OA_VALIDATION_WORKSPACE_ID` are no longer recognised.
+- **Missing-var error message** updated: `Missing required environment variables TESTING_TENANT_ID and/or TESTING_WORKSPACE_ID` (was: `OA_VALIDATION_*`).
+- **No backward compatibility.** Per Architecture Principle #11, the runner does NOT fall back to the old names. Deploy pipelines and container env files must ship `TESTING_*`. A biz service that starts with only `OA_VALIDATION_*` in env will fail Tier-1 validation on first cookbook execution.
+
+### Migration
+
+Every biz-service env-template file under `api_biz/*/config/env-templates/*.env` has been updated in the same session (Fáze B2 in the biz-services alignment). Deployment steps:
+
+1. `npm publish @onlineapps/conn-orch-validator@3.3.0`
+2. In each `api_biz/*/package.json`: exact `"@onlineapps/conn-orch-validator": "3.3.0"` + `npm install`
+3. Restart containers; `init.sh` regenerates `config/env-active/*.env` from the updated templates so the new `TESTING_*` names land in the runtime env.
+
+### Rationale
+
+- The `OA_VALIDATION_` prefix was semantically overloaded (`OA_VALIDATION_*` sounds like it could be a general-purpose "validation" flag, not specifically a cookbook-runner probe).
+- `TESTING_*` is the canonical instance of the `TESTING_*` category defined in `env-conventions.md` — values that legitimately run in dev + CI + production because the Tier-1 cookbook runner fires everywhere.
+- Rename enforced by `api/scripts/lint-env-prefixes.sh` (0 violations across the workspace as of the same-day commits).
+
+### Tests
+
+- `CookbookTestRunner.testingPrefix.test.js` (3 tests) — GREEN. Asserts source references only the new names, missing-var errors mention `TESTING_*`.
+- Existing `CookbookTestRunner.handlerDispatch.test.js`, `resolveHeaders.test.js`, `CookbookTestRunner.integration.test.js`, and `jest.config.js` all updated to set/reference `TESTING_*`.
+
+## [3.2.3] — Pre-3.3.0 baseline
+
+Last version reading `OA_VALIDATION_TENANT_ID` / `OA_VALIDATION_WORKSPACE_ID`. Documented in `api/docs/biz/40-cookbooks/test-env-vars.md` Status section as historical.

package/README.md

@@ -124,13 +124,13 @@ ServiceStructureValidator.getStandardLevels();
 // [{ level: 'v1.0', name: 'Base Service Standard', since: '2025-06-01' }, ...]
 ```
 
-**Related:** [Service Endpoints — Standard Levels](/docs/standards/SERVICE_ENDPOINTS.md#implementation-standard-levels), [Error Handling Standard](/docs/standards/ERROR_HANDLING.md#business-service-error-standard)
+**Related:** [Biz Service Canonical Shape — Implementation Standard Levels](/docs/biz/00-model/service-shape.md#implementation-standard-levels), [Error Handling Standard](/docs/standards/ERROR_HANDLING.md#business-service-error-standard)
 
 ## Related Documentation
 
 - [SERVICE_REGISTRATION_FLOW.md](/services/hello-service/docs/SERVICE_REGISTRATION_FLOW.md)
 - [/docs/architecture/validator.md](/docs/architecture/validator.md)
-- [/docs/standards/OPERATIONS.md](/docs/standards/OPERATIONS.md)
+- [/docs/biz/30-operations/schema-v3.md](/docs/biz/30-operations/schema-v3.md)
 - [/docs/standards/ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md)
 - [@onlineapps/service-validator-core](/shared/service-validator-core/README.md)
 

package/docs/DESIGN.md

@@ -13,7 +13,7 @@ Validation framework for OA Drive microservices. Drives two flows:
    of individual biz services.
 
 The single source of truth for service endpoint metadata is
-[`operations.json`](../../../docs/standards/operations-registry-contract.md).
+[`operations.json`](../../../docs/biz/30-operations/registration-wire.md).
 OpenAPI iteration (`paths`/`operationId`) is NOT supported — that legacy
 surface was removed together with the now-retired `ServiceValidator` /
 `TestOrchestrator` / `ServiceTestHarness` classes.
@@ -56,7 +56,7 @@ surface was removed together with the now-retired `ServiceValidator` /
   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)).
+  [operations-registry-contract.md §3](../../../docs/biz/30-operations/registration-wire.md)).
 - Biz-service templates import `createPreValidationTests` /
   `createServiceReadinessTests` from this package for their own test suites.
 
@@ -75,6 +75,6 @@ surface was removed together with the now-retired `ServiceValidator` /
 
 ## 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
+- [operations-registry-contract.md](../../../docs/biz/30-operations/registration-wire.md) — operations.json schema
+- [test-runner-flow.md](../../../docs/biz/40-cookbooks/test-runner-flow.md) — required `example`/`default` fields for probes + full dispatch mechanics
 - [validator.md](../../../docs/architecture/validator.md) — architecture overview

package/jest.config.js

@@ -1,7 +1,7 @@
 'use strict';
 
-process.env.OA_VALIDATION_TENANT_ID = process.env.OA_VALIDATION_TENANT_ID || '99';
-process.env.OA_VALIDATION_WORKSPACE_ID = process.env.OA_VALIDATION_WORKSPACE_ID || '200';
+process.env.TESTING_TENANT_ID = process.env.TESTING_TENANT_ID || '99';
+process.env.TESTING_WORKSPACE_ID = process.env.TESTING_WORKSPACE_ID || '200';
 
 module.exports = {
   testEnvironment: 'node',

package/package.json

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

package/src/CookbookTestRunner.js

@@ -21,7 +21,7 @@ const { resolveHeaders } = require('./utils/resolveHeaders');
  * matching the shape ServiceWrapper.ContextBuilder produces in production
  * (see api/docs/architecture/biz-service-invocation-model.md §5). Handlers
  * that need DB access import sequelize directly from their own
- * src/config/database.js module (see standards/biz-service-onboarding.md §9a);
+ * 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
  * something it genuinely needs is missing.
  *
@@ -185,10 +185,14 @@ class CookbookTestRunner {
       // { modulePath, exportName } (v3 handler dispatch is the only mode).
       const spec = await this.resolveOperation(step.service, step.operation);
 
-      const rawTenantId = process.env.OA_VALIDATION_TENANT_ID;
-      const rawWorkspaceId = process.env.OA_VALIDATION_WORKSPACE_ID;
+      // Env-var contract (docs/biz/40-cookbooks/test-env-vars.md +
+      // docs/biz/60-templates/env-conventions.md): TESTING_* prefix marks
+      // values that legitimately ship to production because Tier-1 cookbook
+      // runner fires at every service startup, including in prod.
+      const rawTenantId = process.env.TESTING_TENANT_ID;
+      const rawWorkspaceId = process.env.TESTING_WORKSPACE_ID;
       if (!rawTenantId || !rawWorkspaceId) {
-        throw new Error('[CookbookTestRunner] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
+        throw new Error('[CookbookTestRunner] Missing required environment variables TESTING_TENANT_ID and/or TESTING_WORKSPACE_ID');
       }
       // Coerce numeric env vars to integers so ctx matches production
       // ContextBuilder (which receives already-typed values from the MQ envelope).
@@ -225,7 +229,7 @@ class CookbookTestRunner {
    * handler(input, ctx). Mirrors the production ContextBuilder shape
    * (see api/docs/architecture/biz-service-invocation-model.md §5) with
    * all connector slots set to null — handlers that need DB access use
-   * direct sequelize import per standards/biz-service-onboarding.md §9a.
+   * direct sequelize import per biz/60-templates/onboarding-checklist.md §9a.
    */
   async _dispatchViaHandler({ step, spec, testConfig, validationTenantId, validationWorkspaceId, result, startTime }) {
     const stepTimeout = testConfig.timeout || this.timeout;

package/src/ServiceReadinessValidator.js

@@ -12,7 +12,7 @@ const CookbookTestUtils = require('./CookbookTestUtils');
  * adopted in-process handler invocation.
  *
  * @see /api/docs/architecture/biz-service-invocation-model.md §5.3
- * @see /api/docs/standards/validation-probe-contract.md
+ * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (input probe contract)
  */
 class ServiceReadinessValidator {
   constructor(options = {}) {

package/src/helpers/README.md

@@ -146,7 +146,7 @@ If validation fails, clear error messages are shown:
    ✗ Service configuration missing: conn-config/config.json
      Type: MISSING_CONFIG
      File: conn-config/config.json
-     Fix: Create config.json with service metadata. See: /docs/standards/SERVICE_TEMPLATE.md
+     Fix: Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md
 
 ⚠️  WARNINGS (1):
 

package/src/index.js

@@ -7,8 +7,8 @@
  * Production entry point: {@link ValidationOrchestrator} (6-step pre-validation
  * driven by operations.json — OpenAPI path iteration is NOT supported).
  *
- * @see /api/docs/standards/operations-registry-contract.md §3 (operations.json)
- * @see /api/docs/standards/validation-probe-contract.md (validation probes)
+ * @see /api/docs/biz/30-operations/registration-wire.md §3 (operations.json)
+ * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (validation probes)
  * @see /api/docs/architecture/validator.md (validator architecture)
  */
 

package/src/validators/ServiceStructureValidator.js

@@ -223,7 +223,7 @@ class ServiceStructureValidator {
           level: nextLevel.level,
           check: check.id,
           message: `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
-          fix: `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/standards/SERVICE_TEMPLATE.md`
+          fix: `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/biz/60-templates/service-template.md`
         });
       }
     }
@@ -305,7 +305,7 @@ class ServiceStructureValidator {
         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)',
-        fix: 'Create config.json with service metadata. See: /docs/standards/SERVICE_TEMPLATE.md'
+        fix: 'Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md'
       });
     } else {
       try {
@@ -328,7 +328,7 @@ class ServiceStructureValidator {
         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)',
-        fix: 'Create operations.json. See: /docs/standards/OPERATIONS.md'
+        fix: 'Create operations.json. See: /docs/biz/30-operations/schema-v3.md'
       });
     } else {
       try {
@@ -603,7 +603,7 @@ class ServiceStructureValidator {
         type: 'MISSING_APP',
         path: 'src/app.js',
         message: 'Express application missing: src/app.js',
-        fix: 'Create src/app.js with Express app. See: /docs/standards/SERVICE_TEMPLATE.md'
+        fix: 'Create src/app.js with Express app. See: /docs/biz/60-templates/service-template.md'
       });
     } else {
       this.info.push('✓ Found src/app.js');