@onlineapps/conn-orch-validator 6.0.0 → 6.0.1

package/README.md

@@ -9,11 +9,16 @@ Coordinates validation across ALL layers (base, infra, orch, business) to ensure
 This is **NOT** a development testing tool. This is a **production validation orchestrator** that:
 
 1. **Validates service structure** - directories, files, configuration
-2. **Validates configuration** - config.json, operations.json compliance
-3. **Validates business logic** - cookbook tests with mocked infrastructure
-4. **Validates HTTP API** - endpoints respond correctly
-5. **Validates connector integration** - all connectors work with service
-6. **Generates validation proof** - cryptographic SHA256 proof for registry
+2. **Validates configuration** - `config.json`, `operations.json` compliance
+3. **Validates the environment contract** - every `env.required` name is set
+4. **Validates operations** - the v3 handler-registry rules
+5. **Validates business logic** - cookbook tests with mocked infrastructure
+6. **Validates connector integration** - the two declarations agree and the environment backs them
+7. **Generates validation proof** - SHA256 proof carried into registration
+
+There is no HTTP step. Biz containers expose no HTTP surface (ADR 0005), so
+nothing here probes an endpoint — the per-operation endpoint probe and the
+`/health` probe were both removed with it.
 
 Used in **Tier 1 Pre-Validation** (offline, before registration) and invoked automatically by ServiceWrapper.
 
@@ -22,18 +27,13 @@ Used in **Tier 1 Pre-Validation** (offline, before registration) and invoked aut
 **You don't use this directly!** ServiceWrapper handles validation automatically:
 
 ```javascript
-// services/my-service/index.js
-const { ServiceWrapper } = require('@onlineapps/service-wrapper');
-
-const wrapper = new ServiceWrapper({
-  service: app,
-  serviceRoot: __dirname
-});
-
-// Validation happens automatically
-await wrapper.initialize();
+// index.js of a biz service — the whole file
+require('@onlineapps/service-wrapper').bootstrap(__dirname);
 ```
 
+`bootstrap()` builds the wrapper from `src/config`, and `wrapper.initialize()`
+runs Tier-1 validation in phase 0.2 — before MQ connects, before registration.
+
 **No test files needed in business service!**
 
 ---
@@ -43,7 +43,7 @@ await wrapper.initialize();
 1. **Service Structure** - directories and files exist
 2. **Config Files** - valid JSON, required fields
 3. **Environment Contract** - every variable the contract declares `env.required` is set
-4. **Operations Compliance** - follows OPERATIONS.md standard
+4. **Operations Compliance** - every operation declares `handler`, `bundle_scope`, `input`, `output`, and none carries a retired v2 field (`endpoint`, `method`, `path`); a missing `description` is a warning
 5. **Cookbook Tests** - business logic + integration (MOCKED infra)
 6. **Connector Integration** - the connector declarations agree and the environment backs them
 
@@ -116,7 +116,7 @@ services/my-service/
     "serviceName": "hello-service",
     "version": "1.0.0",
     "validator": "@onlineapps/conn-orch-validator",
-    "validatorVersion": "2.0.6",
+    "validatorVersion": "<this package's version, read from its package.json>",
     "validatedAt": "2025-10-22T10:30:45.123Z",
     "testsRun": 15,
     "testsPassed": 15,
@@ -127,29 +127,68 @@ services/my-service/
 ```
 
 **Proof Lifecycle:**
-- **Valid for:** 7 days OR until service fingerprint changes
-- **Fingerprint:** SHA256 hash of (version + operations + dependencies + config)
-- **Revalidation:** Automatic if proof missing/invalid/expired
-- **Registry:** Accepts service with valid proof (skips Tier 2 validation)
+- **Written:** on every successful validation, i.e. on every boot. There is no
+  proof cache — the one that existed skipped steps 1-3 and 5-6 to save 6 ms and
+  bought a window of up to seven days in which validation asserted something no
+  longer true. It is gone, and with it the 7-day expiry it needed.
+- **Fingerprint:** SHA256 over (service version + operations + `@onlineapps/*`
+  dependencies + config + infra files + cookbooks + seeds), stored in the proof
+  as `contractFingerprint`. Nothing reads it back to skip work; it records what
+  the run covered.
+- **Registry:** the proof travels in the registration payload
+  (`ServiceWrapper.js`, `validationProof` field) — a service that fails
+  validation never reaches registration, because phase 0.2 throws.
 
 ---
 
+## Readiness scoring (`ServiceReadinessValidator`)
+
+A separate scorer from the six-step Tier-1 run above. Tier-1 stopped calling it
+in 2026-08 — its verdict was a strict function of steps 2 and 3, so it announced
+a result it never independently reached. What consumes it today is
+`helpers/createServiceReadinessTests`, and through it every biz repo's
+`tests/bootstrap/` suite.
+
+| Check | Weight | Required | What it means |
+|---|---|---|---|
+| `operations` | 80 | yes | the v3 rules — `handler`, `bundle_scope`, `input`, `output`, no retired v2 field |
+| `cookbook` | 15 | no | runs only when a `testCookbook` is passed; structural validation of it |
+| `registry` | 5 | no | runs only when a `registry` is passed; the service can register and its version does not clash |
+
+`ready` is true when every required check passed AND the score is at least 60.
+The retired `health` check's 20 points folded into `operations` (ADR 0005), so
+the maximum is still 100.
+
+**Every evaluation writes exactly one line** through the injected logger:
+`[ServiceReadinessValidator] Readiness evaluated` with a structured object
+(`serviceName`, `score`, `maxScore`, `ready`, `checks` as `{name: {passed,
+score}}`, `errors`, `warnings`). A refusal adds one `error`-level line,
+`[ServiceReadinessValidator] Service not ready`. There is no per-check
+narration: one evaluation, one complete, machine-readable record.
+
+The constructor requires a logger with all four of `info`, `warn`, `error`,
+`debug`, and says which one is missing when it is not — see
+`docs/governance/confirmations/connector-logger-contract.md`.
+
 ## Implementation Standard Levels
 
 The validator evaluates each service against cumulative implementation standards. Levels are ordered — each requires all previous to pass:
 
 | Level | Name | Checks | Since |
 |-------|------|--------|-------|
-| **v1.0** | Base Service Standard | `config/service/`, `src/app.js`, `index.js`, valid `config.json` + `operations.json`, `@onlineapps/service-wrapper` dep | 2025-06 |
+| **v1.0** | Base Service Standard | `config/service/`, `src/`, `tests/`, `src/handlers/` (v3 handler modules — ADR 0005 replaced `src/app.js`), `index.js`, `config.json` with `service.name`, `operations.json` with an `operations` object, `@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 |
+| **v1.2** | Business Error Handling Standard | `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 |
+| **v1.3** | Zero-HTTP Shape (ADR 0005) | `src/app.js` absent, `src/routes/` absent, `src/middlewares/` absent, `express` not in dependencies | 2026-08 |
 
 **Key properties:**
 - **Cumulative** — v1.2 requires v1.0 + v1.1 to also pass
 - **Baked into validator** — older validator versions naturally know fewer levels (backward compatible)
 - **Warnings** — next unsatisfied level generates `STANDARD_LEVEL_GAP` warnings with specific missing checks
-- **Exposed in `/info`** — ServiceWrapper's `GET /info` endpoint returns the highest satisfied level
-- **In validation results** — `validate()` returns `standardLevel` and `standardDetails`
+- **In validation results** — `ServiceStructureValidator.validate()` returns
+  `standardLevel` and `standardDetails`. That is the only place the level
+  surfaces: `GET /info` used to carry it and was retired with the rest of the
+  HTTP surface (ADR 0005), and nothing has taken its place
 
 ```javascript
 // Programmatic access
@@ -168,12 +207,7 @@ ServiceStructureValidator.getStandardLevels();
 
 ## Related Documentation
 
-- [SERVICE_REGISTRATION_FLOW.md](/services/hello-service/docs/SERVICE_REGISTRATION_FLOW.md)
 - [/docs/architecture/validator.md](/docs/architecture/validator.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)
-
----
-
-*Last updated: 2026-03-24*

package/docs/DESIGN.md

@@ -5,13 +5,14 @@
 Validation framework for OA Drive microservices. Drives two flows:
 
 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/`.
+   structure (config files, package.json), the environment contract, the v3
+   operations rules and the cookbook tests, then produces a signed
+   `validation-proof.json` stored under `conn-runtime/`. Nothing is probed over
+   HTTP: biz containers expose no endpoints (ADR 0005).
 2. **Readiness checks** — a reusable probe (`createServiceReadinessTests`)
    consumable from the `tests/bootstrap/` suites of individual biz services.
 
-The single source of truth for service endpoint metadata is
+The single source of truth for service operation metadata is
 [`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` /
@@ -38,8 +39,9 @@ surface was removed together with the now-retired `ServiceValidator` /
 
 ### Production Validation
 
-- `ValidationOrchestrator` — 5-step pre-validation pipeline (structure, config,
-  operations, cookbooks, connectors), emits proof
+- `ValidationOrchestrator` — six-step pre-validation pipeline (structure,
+  config, environment contract, operations, cookbooks, connectors), emits proof.
+  Each step announces itself as `Step N/6` through the injected logger
 - `ServiceReadinessValidator` — score-based checks (operations 80 / cookbook 15
   / registry 5). Not used by the orchestrator: its only consumer is
   `createServiceReadinessTests`, and through it the biz repos'
@@ -52,27 +54,31 @@ surface was removed together with the now-retired `ServiceValidator` /
 
 ### Test Suite Helpers
 
-- `createServiceReadinessTests(options)` — Jest suite generator
+- `createServiceReadinessTests(testsDir, options)` — Jest suite generator
 
 ## Integration Points
 
 - `@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/biz/30-operations/registration-wire.md)).
-- The biz repos import `createServiceReadinessTests` from this package in their
-  `tests/bootstrap/service-readiness.test.js` (`converter`, `ingest`,
-  `hello-service`).
+  wrapper startup, in phase 0.2. **There is no proof cache**: the full
+  validation runs on every boot, and `conn-runtime/validation-proof.json` is its
+  output, not its shortcut. The cache that once lived here skipped most steps to
+  save milliseconds and bought a window in which validation asserted something
+  no longer true; the fingerprint it keyed on covered less than it claimed. The
+  proof travels into registration (see
+  [registration-wire.md](../../../docs/biz/30-operations/registration-wire.md)).
+- Biz repos import `createServiceReadinessTests` from this package in their
+  `tests/bootstrap/service-readiness.test.js`. Which repos do so changes with
+  the service headcount, so grep for the symbol rather than trusting a list
+  written here.
 - Pre-validation is driven by the `oa-biz-ci-gate run-prevalidation` subcommand,
   not by a Jest suite generator.
 
 ## 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
+1. **Service contract** — structure, config files and the v3 operations rules
+2. **Environment contract** — every name declared `env.required` is set
+3. **Workflow capability** — can process cookbooks, in-process, with mocks
+4. **Connector contract** — the two declarations agree and the environment backs them
 
 ## What We DO NOT Test
 

package/package.json

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

package/src/helpers/README.md

@@ -15,43 +15,53 @@ Instead of **copying test code** between services, we provide **reusable test he
 
 ### createServiceReadinessTests
 
-**Purpose:** Integration test for service HTTP API readiness
+**Purpose:** a jest suite proving a service is ready — its shape on disk and its
+v3 operations contract. Nothing is started and nothing is called over the
+network: biz containers run zero HTTP (ADR 0005), so there is no port to bind,
+no endpoint to probe and no `/health` to check.
 
 **File:** `createServiceReadinessTests.js`
 
 **What it does:**
-- Validates service structure (config/service/, src/handlers/, package.json)
-- Validates configuration files (config.json, operations.json)
-- Tests all operations endpoints
-- Validates health endpoint
-- Auto-generates cookbook tests (with mocks)
-- Tests registry compatibility (with mocks)
-- Scores 100/100 with all checks
+- Validates service structure (config/service/, src/, tests/, src/handlers/, package.json) and THROWS before any test runs if it fails
+- Loads `config/service/config.json` and `config/service/operations.json` — the only configuration path
+- Scores readiness through `ServiceReadinessValidator` (operations, plus cookbook and registry when the optional checks are on)
+- Synthesises a cookbook from the declared operations, with mock input generated from each `input` schema
+- Uses `MockRegistry` for the registry check — nothing real is contacted
+- Asserts every operation declares `handler` (matching `handlers/<path>#<export>`) and a valid `bundle_scope`, and carries no retired v2 `endpoint` / `method`
 
 **Usage:**
 ```javascript
-// services/my-service/tests/integration/service-readiness.test.js
+// <service>/tests/bootstrap/service-readiness.test.js
 const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
 
 createServiceReadinessTests(__dirname);
 ```
 
+The service root is resolved two levels up from the directory you pass, so the
+file belongs in `tests/<something>/`.
+
 **Options:**
 ```javascript
 createServiceReadinessTests(__dirname, {
-  testPort: 5556,              // Test server port (default: 5556)
   includeOptionalChecks: true, // Cookbook & registry checks (default: true)
-  timeout: 15000               // Test timeout in ms (default: 15000)
+  timeout: 15000,              // Test timeout in ms (default: 15000)
+  logger: myLogger             // Logger for ServiceReadinessValidator (default: console)
 });
 ```
 
-**Score Breakdown:**
-- operations: 30 points (required)
-- endpoints: 30 points (required)
-- health: 20 points (required)
-- cookbook: 15 points (optional, with mocks)
-- registry: 5 points (optional, with mocks)
-- **Total: 100/100**
+`logger` defaults to `console` on purpose — in a bootstrap suite stdout is the
+report the developer reads. See
+[FALLBACKS_INVENTORY.md](/docs/standards/FALLBACKS_INVENTORY.md) §5.6.
+
+**Score Breakdown** (owned by `ServiceReadinessValidator`):
+- operations: 80 points (required)
+- cookbook: 15 points (optional, structural validation of the synthesised cookbook)
+- registry: 5 points (optional, MockRegistry)
+- **Total: 100/100** — ready requires every required check to pass and a score of at least 60
+
+With `includeOptionalChecks` on, the suite asserts the full 100; with it off, it
+asserts at least 80 and a passing `operations` check.
 
 ---
 
@@ -70,12 +80,12 @@ The helper uses `ServiceStructureValidator` to validate service structure BEFORE
 
 ✅ ALL CHECKS PASSED
 
-   ✓ Found Configuration directory: config/service
+   ✓ Found Configuration directory
    ✓ Found Source code directory: src
    ✓ Found Tests directory: tests
    ✓ Found valid config.json
    ✓ Found valid operations.json
-   ✓ Found src/app.js
+   ✓ Found src/handlers/
    ✓ Found 3 cookbook test(s)
 
 ═══════════════════════════════════════════════════════════════
@@ -107,20 +117,21 @@ If validation fails, clear error messages are shown:
 The helper automatically detects and loads:
 
 ```javascript
-// Service root (2 levels up from tests/integration/)
-const serviceRoot = path.resolve(__dirname, '../..');
+// Service root (2 levels up from the directory you passed)
+const serviceRoot = path.resolve(testsDir, '../..');
 
-// Standard file locations
-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'));
+// The only configuration path — the legacy conn-config/ layout is gone
+const config = JSON.parse(fs.readFileSync(path.join(serviceRoot, 'config/service/config.json'), 'utf-8'));
+const operations = JSON.parse(fs.readFileSync(path.join(serviceRoot, 'config/service/operations.json'), 'utf-8'));
 
 // Extract metadata
 const serviceName = config.service.name;
 const serviceVersion = config.service.version;
-const healthEndpoint = config.wrapper?.health?.endpoint || '/health';
 ```
 
+Nothing loads `src/app.js` and nothing reads a health endpoint: both belonged to
+the Express surface ADR 0005 removed.
+
 No service-specific code needed!
 
 ---
@@ -133,7 +144,7 @@ When creating new generic test helpers:
 2. **Accept testsDir as first parameter:** `function create...(testsDir, options)`
 3. **Calculate service root:** `const serviceRoot = path.resolve(testsDir, '../..');`
 4. **Validate structure first:** Use `ServiceStructureValidator`
-5. **Load standard files:** config.json, operations.json, app.js
+5. **Load standard files:** `config/service/config.json`, `config/service/operations.json`
 6. **Provide clear output:** Log validation results, test progress
 7. **Export single function:** `module.exports = { create...Tests };`
 8. **Update index.js:** Add to exports
@@ -176,8 +187,3 @@ module.exports = { createMyTests };
 - [/tests/TESTING.md](/tests/TESTING.md) - SPOT principles
 - [/shared/connector/conn-orch-validator/README.md](/shared/connector/conn-orch-validator/README.md) - Package documentation
 - [/shared/connector/conn-orch-validator/docs/DESIGN.md](/shared/connector/conn-orch-validator/docs/DESIGN.md) - Design principles
-
----
-
-*Last updated: 2025-10-21*
-*Maintained by: OA Drive Core Team*