@onlineapps/conn-orch-validator 3.3.2 → 4.0.1

package/CHANGELOG.md

@@ -2,6 +2,364 @@
 
 All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [Unreleased]
+
+> ⚠ Neither this entry nor the connector-step work of `dcddb862` is published.
+> The last version on NPM is 3.3.2, so **no biz CI run sees any of it yet**.
+
+### Fixed — validator findings pointed at an archived document (DÁVKA 51)
+
+`ServiceStructureValidator` sent readers of five findings to
+`biz-service-invocation-model.md` — twice by name, three times under its `RFC`
+nickname. The document was archived; following the pointer found nothing, so the
+finding stayed unfixed. `automation-gates.md` §1 requirement 4 asks a gate for
+*the exact command that fixes it*, and a dead citation is the opposite of that.
+
+- `INVALID_OPERATIONS_STRUCTURE`, `SCHEMA_VERSION_MISMATCH`,
+  `MISSING_OPERATION_FIELD` and `V2_FIELD_PRESENT` now carry the fix in the text
+  and name the file to edit (`config/service/operations.json`) — no citation to
+  follow at all.
+- The two `@see` headers above that code point at the live owner,
+  `api/docs/biz/30-operations/schema-v3.md`.
+- A sweep test resolves every `.md` path in a `message`/`fix` string literal
+  against the checkout and fails on the first one that is not there, so the next
+  archived document is caught the day it moves.
+
+### BREAKING — v1.2 checks the business-error CONTRACT, not the package name (DÁVKA 50)
+
+**Major.** The v1.2 verdict changes for every service that still imports its
+error classes from `@onlineapps/service-common`, and for every service whose
+handlers do not reach a business-error declaration at all.
+
+Owner decision: `api/docs/governance/confirmations/business-error-contract.md`
+(`20260829-1500-business-error-contract-001`, CONFIRMED).
+
+v1.2 used to ask *"does this service depend on `@onlineapps/service-common` and
+import an error class FROM IT?"* — `dep_service_common` and
+`business_error_usage`. Both demanded the hierarchy that DÁVKA 29 retired, so a
+service that had already migrated to the wrapper's classes **failed the gate for
+being correct**. A check keyed on a package name goes stale at every move; a
+check keyed on the contract does not.
+
+- **Removed** `dep_service_common`. `@onlineapps/service-common` is no longer
+  required in `dependencies` at any standard level.
+- **Removed** `business_error_usage`, replaced by **`business_error_contract`**:
+  at least one file under `src/**` imports a `BusinessError` family from
+  `@onlineapps/service-wrapper`, **or** declares the brand
+  `onlineapps.businessError`. A service's own error class satisfies the check by
+  declaring the brand; inheriting from the wrapper's base class is the
+  convenient way to get it, not the only permitted one.
+  The scope is the whole of `src/`, deliberately — one rule in one sentence
+  (`automation-gates.md` §1 requirement 2, *Simple*). A first cut scoped it to
+  `src/handlers/**` plus the `src/lib/**` modules a handler requires; measured
+  against the eight services it failed `biz-converter` and `biz-ingest`, both of
+  which declare the contract in `src/lib/` and reach it through `src/services/`.
+  A static check cannot prove a `throw` reaches a handler in any case — it can
+  only see the declaration — so the narrower rule bought no accuracy and cost two
+  false findings.
+- **Added** `no_retired_error_hierarchy`: no file under `src/**` imports an error
+  class from `@onlineapps/service-common`. The finding is
+  `[Context] Problem - Expected/Fix` and names **every** offending file with the
+  exact replacement import line. Scoped to what
+  `service-common/src/errors/BusinessError.js` exports — `ScopedRegistryError`
+  belongs to the live scoped-registry helper and is not part of the retired
+  hierarchy, so importing it stays legal.
+- A v1.2 check that carries its own `fix` now emits that message verbatim in its
+  `STANDARD_LEVEL_GAP` warning, instead of the generic `missing …` wrapper that
+  would have buried the file list.
+
+**Measured over all eight biz services before the change landed**
+(`automation-gates.md` §3 — a gate arrives with the compliance work, never ahead
+of it): `converter`, `emailer`, `hello-service`, `ingest`, `invoicing`,
+`property` PASS both checks and reach v1.3; `meta` fails both — 8 files still on
+the retired hierarchy, so it declares no wrapper contract either; `pdfgen` fails
+`business_error_contract` alone, having no business-error class at all (every
+throw in `src/handlers/pdf.js` is a plain `Error`, i.e. a masked 500 today). The
+gate reaches the services with the wrapper release that carries the brand, so
+each migrates its imports in the same change that bumps the wrapper.
+
+**Defect found by that measurement, fixed here:** the import scanner matched the
+destructuring body with `[\s\S]*?`, which starts at the nearest preceding
+`const {` and swallows whole lines to reach the right `require`. On
+`api_biz/meta/src/handlers/persons.js:10-11` — an unrelated `models`
+destructuring directly above the service-common one — that silently dropped
+`ValidationError` from the finding. The body is now `[^{}]*?`.
+
+### Added — the environment contract (F16)
+
+**A service declares the environment it needs, in the file where it already
+declares its connectors and its database.** The platform had an enforcement
+engine (`@onlineapps/runtime-config` schemas throw on a missing required key)
+and no declaration: of 56 variables measured across the eight biz services,
+21 were enforced by `ConfigLoader`, 5 by the connector contract and the rest by
+nothing at all. So `EMAIL_PROVIDER_LIVE_MODE` could be read by biz-emailer while
+no template ever set it — live mail was silently off, and nothing said a word.
+
+- **`integration-contract.json` gains an optional `env` block** —
+  `env.required[]` / `env.optional[]`, items `{ name, why }`. `why` is
+  mandatory. `normalizeIntegrationContract()` validates the shape strictly:
+  unknown keys, a non-array list, a bare string item, a name that is not
+  SCREAMING_SNAKE_CASE, a missing `why`, a duplicate name, and a name already
+  covered by a `${VAR}` config placeholder or by a required connector are all
+  hard errors naming the fix.
+- **`oa-biz-ci-gate verify-env-contract`** (new subcommand, and folded into
+  `verify-contract` between the installation contract and R6) checks
+  COMPLETENESS: every environment name the service repository visibly reads is
+  declared or covered. It prints its measurement boundary on every run —
+  `config/service/*.json` plus literal `process.env.X` / `env.X` /
+  `requireEnv('X')` in `src/`, `index.js`, `scripts/`, and the number of dynamic
+  `process.env[key]` sites it could not resolve. Environment read inside
+  `node_modules` is out of reach and is declared by hand (variant D of the
+  design would close that).
+- **`ValidationOrchestrator` step 3, "Environment Contract"** checks PRESENCE
+  before any handler runs and long before a connector opens: a declared
+  `required` name that is unset fails with
+  `[EnvContract] Missing environment variable - <NAME> is required (<why>). Fix: …`.
+  This is defect D2 — `SECRETS_MASTER_KEY` used to fail in
+  `ServiceWrapper.js:916`, after MQ registration, where the symptom looked like
+  a broken registration.
+- **A contract with no `env` block is skipped OUT LOUD** by both consumers. That
+  state is legitimate until every repo adopts the declaration; a step that says
+  nothing about what it did not check reads as a guarantee it never gave
+  (`automation-gates.md` §5).
+
+Measured against the eight live repos on 2026-08-27 (read-only): biz-invoicing
+and biz-pdfgen pass with nothing declared; biz-emailer reports 13 undeclared
+reads, biz-hello 6, biz-meta 2, biz-converter / biz-ingest / biz-property 1 each.
+That is the gate doing its job before adoption, not a regression — it lands with
+the declarations, per `automation-gates.md` §3 (no grandfathering).
+
+### BREAKING — step numbering
+
+- `ValidationOrchestrator` announces `Step n/6`; `results.steps` keys are
+  `structure, config, env, operations, cookbooks, connectors`.
+
+**Tier-1 drops to five steps: the readiness step is removed, and with it the last `url`.**
+
+### BREAKING — `ValidationOrchestrator`
+
+- **Step 5 "Service Readiness" removed.** The remaining steps are renumbered and
+  the log now reads `Step n/5`. `results.steps.readiness` is no longer emitted;
+  `results.steps` keys are `structure, config, operations, cookbooks, connectors`.
+- `ValidationOrchestrator.validateReadiness()` removed; the orchestrator no
+  longer constructs a `ServiceReadinessValidator`.
+- `options.serviceUrl` is **no longer required** and is no longer stored. It is
+  accepted and ignored, so `ServiceWrapper` and the biz
+  `scripts/run-pre-validation.js` need no change. Previously a *required*
+  option that no line of code read — a service with `SERVICE_URL` unset failed
+  Phase 0.2 for the sake of a value nobody wanted.
+
+Why the step went rather than shrinking: its verdict was a strict function of
+steps 2 and 3. Its per-operation rules were step 3's rules, copied loop for
+loop; its two extra guards ("operations must be an object", "no operations
+defined") are step 2's `operations.json has no operations defined`. Across a
+valid baseline plus 13 mutations covering every rule it never once disagreed
+with `step2 && step3`, and against the eight live biz services it emitted a
+single check, scored 80 out of a `maxScore` of 100 this call path could never
+reach, and compared it to a `score >= 60` threshold the one remaining weight had
+made decorative. Measured 0 ms. It could not fail a service the earlier steps
+passed, so it announced a sixth verdict it never independently reached — the
+defect the connector step was fixed for in `dcddb862`, one step earlier.
+
+### Changed — nothing lost with it
+
+- **Step 3 now warns on an operation with no `description`.** That was the
+  readiness step's only non-duplicate signal, and it never reached anyone: the
+  step returned `{valid, errors}` and dropped `warnings`. `validateOperations()`
+  now returns `warnings` and `runFullValidation()` puts them in
+  `results.warnings`.
+
+### Fixed
+
+- **`runFullValidation()` crashed on a failing connector step.** `dcddb862`
+  changed `validateConnectors()` to return `{valid, errors}`; the caller still
+  spread `.warnings`. Any service that actually failed the contract — the one
+  case the step exists for — aborted with
+  `results.steps.connectors.warnings is not iterable` and lost every finding.
+  Reproduced against biz-pdfgen and biz-property. Severity is unchanged: the
+  connector contract stays non-critical, reported as warnings.
+- **Per-check score is recorded.** `createServiceReadinessTests` prints
+  `checkResult.score`; nothing ever assigned it, so every biz bootstrap run
+  printed `0 points` beside checks that had just been awarded full weight,
+  under a total that contradicted them.
+
+### `ServiceReadinessValidator` — kept, `url` gone
+
+The class stays: its cookbook and registry checks are used by
+`createServiceReadinessTests`, and through it by `tests/bootstrap/` in
+`api_biz/hello-service`, `api_biz/converter` and `api_biz/ingest`. That helper's
+signature is unchanged, and it never passed a `url`.
+
+- `service.url` no longer destructured; `results.serviceUrl` no longer emitted;
+  `generateReport()` no longer prints a `URL:` line naming an address nothing
+  listens on.
+
+### Tests
+
+Unit suite 283 → **322 GREEN**. `ServiceReadinessValidator` had no unit tests at
+all — which is how a dead parameter survived the removal of its probe; it now
+has 22, pinning every operations rule explicitly so a future divergence from
+step 3 is visible rather than silent.
+
+### Added — the biz `scripts/*` duplication moves into the gate (F15#3)
+
+Two roles that lived as copied per-service scripts become subcommands. Nothing
+in any service repo changes until its pin is bumped; activation is F8.
+
+- **`verify-install-contract`** — the setup-doc package every repo carries, plus
+  the `migrations/BASELINE` + `SEED/{production_like,test_only}` SQL tree and its
+  four headers, required of every repo whose contract declares a database.
+  Replaces nine copies of `scripts/verify-installation-docs-sql-contract.sh`
+  (eight biz repos + `api/`).
+  **Whether the SQL half applies is now DERIVED from `integration-contract.json`**
+  instead of a hand-maintained `REPO_HAS_DB` literal per copy. The literal had
+  drifted: converter, hello-service and ingest declared `false` while their
+  contract declares a database, so the SQL half silently checked nothing in three
+  repos while still printing `PASS`. `docs/setup/` is the single accepted
+  location — property's `docs/80-setup/` does not satisfy it.
+- Folded into **`verify-contract`**, on the precedent of `e538fc8d`: a version
+  bump activates it, with no per-repo CI edit to forget.
+- **`run-prevalidation`** — runs the service's cookbooks offline against mocked
+  infrastructure and writes `conn-runtime/validation-proof.json`. Replaces five
+  copies of `scripts/run-pre-validation.js`: four identical, plus property's
+  16-line stand-in that counted `.json` files and printed OK without running a
+  cookbook or writing a proof, while wired to the same `npm run test:cookbooks`.
+  The legacy HTTP dispatch branch is not carried over — every service is v3, so
+  it was unreachable; a non-v3 shape now fails fast instead of silently taking
+  the handler path.
+  `ConfigLoader` is **not** imported here: it lives in `@onlineapps/service-wrapper`
+  (L4) and this package is L3, so the service URL is resolved from the service's
+  own installed wrapper and injected (architecture-principles §7).
+
+### Fixed — a failed cookbook step said `[object Object]`
+
+The scripts interpolated a step's `error` straight into a template literal, so
+an object-shaped failure told the operator nothing. It is now rendered by
+message, then by serialization. On the first real run this turned
+`[object Object]` into `getaddrinfo ENOTFOUND gen_mariadb10.5`.
+
+### Tests
+
+Suite 388 → **422 GREEN** (25 → 30 suites): 21 unit + 13 integration, the latter
+driving the real CLI as a child process and the real `CookbookTestRunner` over
+real v3 handlers. Both new modules were mutation-falsified; removing the
+`verify-contract` fold-in turns exactly one test red.
+
+### Added — the cookbook format check is mandatory, not opt-in (F17)
+
+`version` is a REQUIRED cookbook field, `"2.1.0"` or higher
+(`api/docs/biz/40-cookbooks/format.md` § Required fields). Until now that
+sentence was implemented only in `CookbookTestUtils.validateCookbook`, which is
+reachable only from `tests/bootstrap/service-readiness.test.js` — a wrapper 3 of
+8 biz repos happen to have. The Tier-1 path (`CookbookTestRunner`, step 4 of
+`ValidationOrchestrator`) validated steps and never looked at `version`, so
+**14 of 28 cookbooks across 4 repos (emailer, invoicing, pdfgen, property) carry
+no `version` at all** and every boot said PASS.
+
+- New `src/utils/cookbookFormat.js` — one owner for the rule:
+  `MIN_COOKBOOK_FORMAT_VERSION = '2.1.0'` and `checkCookbookFormatVersion()`
+  returning the problem in `Problem - Expected/Fix` form, or `null`.
+- `CookbookTestRunner.validateCookbook()` checks the format version FIRST, and
+  rejects a payload that is not a JSON object at all. No signature change.
+- `CookbookTestRunner.runCookbook()` appends `(cookbook file: <path>)` to
+  whatever validation rejected, when the cookbook came from a file — a service
+  carries a dozen of them and "a cookbook is malformed" named none.
+- `CookbookTestRunner.loadCookbook()` — a syntax error in a cookbook file now
+  fails as `[CookbookTestRunner] Cookbook file is not valid JSON …` naming the
+  file, instead of a bare `Unexpected token` from `JSON.parse`.
+- `CookbookTestUtils.validateCookbook()` uses the same shared rule, so the
+  readiness path stops accepting an outdated version on presence alone.
+- The cookbooks this package itself synthesises (`CookbookTestUtils`
+  generators, `createServiceReadinessTests`) said `version: '1.0.0'` — the
+  library emitted cookbooks its own gate rejects. They now use the constant.
+
+Nothing changes in the biz repos until F8 bumps the pin; the 3 readiness
+wrappers stay until then (removing them ahead of activation would reopen the
+hole this closes).
+
+### Tests
+
+Suite 422 → **449 GREEN** (30 → 33 suites). RED before the change: a
+version-less and an outdated cookbook both passed Tier-1 step 4
+(`success: true`); the readiness helper scored 100/100 while synthesising a
+`1.0.0` cookbook. New integration suite drives the real
+`ValidationOrchestrator.runCookbookTests()` over real cookbook files on disk,
+and the real `createServiceReadinessTests` over a real service tree — control
+cases assert the existing fixture cookbook still runs unchanged (2 steps, both
+passed) and that the structural messages are untouched.
+
+### Fixed — three defects behind biz-hello's oscillating boot verdict (2026-08-29)
+
+Reported from the publication wave as two open findings: a `count_stub` that
+failed at 1101–5593 ms and passed at 0–916 ms in the same container, and a
+series of `Validation FAILED` in 104–221 ms that nobody could explain. They are
+one causal chain and three separate defects.
+
+- **`expect.duration.max` measured the runner's cold start, not the handler.**
+  `executeStep` started its stopwatch before `resolveOperation()` and before
+  `require()` of the handler module, so the module-load cost was charged to the
+  handler. biz-hello's `count_stub` is a stub returning four constants that
+  never touches the DB, but it is the only cookbook step in that service whose
+  module pulls in `sequelize` + `src/config/database.js`. Measured in the
+  running container with the wrapper already loaded, as at boot: `secretLookup`
+  25 ms, `greetings` 8 ms, `externalHttpPing` 5 ms, `storeAndFetchNote` 9 ms,
+  **`tenantGreetingCount` 2264 ms**. Against a 1000 ms bar the verdict on a
+  healthy service therefore depended on filesystem cache warmth — not
+  predictable, so not a gate (`automation-gates.md` §1.1). A step now reports
+  three numbers: `setupDurationMs` (the runner's own cost), `handlerDurationMs`
+  (the handler's runtime) and `duration` (the unchanged total); the expectation
+  compares `handlerDurationMs`, and the load cost is printed on the step's log
+  line rather than swept away.
+- **A reused runner accumulated results forever.** `ValidationOrchestrator`
+  builds its `CookbookTestRunner` once in the constructor, and
+  `ServiceWrapper._ensureValidationProof` reuses ONE orchestrator across its
+  whole startup retry loop (six attempts, 30 s → 30 min). `runCookbooks()` only
+  ever added to `this.results`, so one transient failure on attempt 1 stayed in
+  `failed` for the life of the process and `success: result.failed === 0` could
+  never return true again. The whole cycle is legible in biz-hello's own log —
+  one process, six attempts, the deficit of 1 riding along and the total
+  climbing by 8 each time, while the step that started it passes in single-digit
+  milliseconds:
+
+  ```
+  7/8 passed    ❌ FAILED (3840ms)   count_stub FAILED (3297ms)   ← cold require
+  15/16 passed  ❌ FAILED (155ms)    count_stub PASSED (5ms)
+  23/24 passed  ❌ FAILED (92ms)     count_stub PASSED (4ms)
+  31/32 passed  ❌ FAILED (160ms)    count_stub PASSED (4ms)
+  39/40 passed  ❌ FAILED (103ms)    count_stub PASSED (2ms)
+  47/48 passed  ❌ FAILED (94ms)     count_stub PASSED (3ms)
+  8/8 passed    ✅ PASSED (556ms)    count_stub PASSED (498ms)    ← new process
+  ```
+
+  Six attempts is exactly the length of `REVALIDATION_FAST_BACKOFF_MS`. The
+  92–221 ms runs are the false verdict in its purest form: full runs in which
+  every step passed, reported as failures, for ~18.5 minutes before the process
+  gave up and exited. `resetResults()` had existed the whole time, with a unit
+  test and **no production caller** (`change-discipline.md` § Removing something
+  removes its declaration); `runCookbooks()` is now that caller.
+- **A failed step never said why.** The log line was `Step count_stub: FAILED
+  (1101ms)` and step 4's only error was `1 cookbook test(s) failed` — the reason
+  lived in `result.validationErrors` / `result.error` and was discarded at both
+  ends, which made a failed boot undiagnosable from its own logs
+  (`automation-gates.md` §5). New `utils/stepFailure.js` is the single owner of
+  that sentence: the runner prints it (with the stack, for a thrown error) and
+  the orchestrator's error list names the cookbook, the step, the operation and
+  the reason.
+
+### Tests
+
+Suite 560 → **572 GREEN** (40 → 43 suites), exit 0. Three new integration
+suites, each RED first against real cookbook files, a real `operations.json`
+and real handler modules required out of a freshly copied service tree:
+`cookbookFailureDiagnostics` (3 of 4 RED — measured
+`info Step throwing-step: FAILED (0ms)` with no reason), `cookbookRepeatedRuns`
+(5 of 5 RED — the second run reported `total: 2`), `cookbookStepDuration`
+(3 of 3 RED — a healthy stub behind a 400 ms module load failed a 150 ms bar).
+Control cases assert what must NOT move: a permanently broken cookbook still
+fails on the second run, a healthy one reports identical numbers on every run,
+a genuinely slow handler still fails the same bar, and a passing cookbook logs
+no failure reason at all.
+
 ## [3.3.2] — 2026-08-17
 
 **ServiceStructureValidator refactor for ADR 0005 / Fáze F6 reality.**

package/README.md

@@ -42,13 +42,52 @@ await wrapper.initialize();
 
 1. **Service Structure** - directories and files exist
 2. **Config Files** - valid JSON, required fields
-3. **Operations Compliance** - follows OPERATIONS.md standard
-4. **Cookbook Tests** - business logic + integration (MOCKED infra)
-5. **Service Readiness** - HTTP API works
-6. **Connector Integration** - all connectors functional
+3. **Environment Contract** - every variable the contract declares `env.required` is set
+4. **Operations Compliance** - follows OPERATIONS.md standard
+5. **Cookbook Tests** - business logic + integration (MOCKED infra)
+6. **Connector Integration** - the connector declarations agree and the environment backs them
 
 **Output:** Validation proof saved to `conn-runtime/validation-proof.json`
 
+> The list said "Service Readiness — HTTP API works" until 2026-08-27. That step
+> was removed on 2026-08-22 under ADR 0005 and this README kept describing it.
+
+---
+
+## Environment contract (`env` block)
+
+One declaration in `config/service/integration-contract.json`, two consumers:
+
+```json
+"env": {
+  "required": [{ "name": "SECRETS_MASTER_KEY", "why": "decrypts per-tenant secrets from SecretBox" }],
+  "optional": [{ "name": "SES_REGION",         "why": "AWS region when the SES provider is live" }]
+}
+```
+
+| Consumer | Direction | Where |
+|---|---|---|
+| `oa-biz-ci-gate verify-env-contract` (also folded into `verify-contract`) | COMPLETENESS — nothing the repo reads is undeclared | CI |
+| `ValidationOrchestrator` step 3 | PRESENCE — every `required` name is set | boot, phase 0.2 |
+
+`why` is mandatory: a required variable nobody can justify is the one nobody
+dares delete.
+
+**The block must not repeat what already covers a name** — a `${VAR}`
+placeholder in `config/service/*.json`, or the endpoint variable of a connector
+the contract declares required. Both are rejected as a duplicate declaration.
+
+**Measurement boundary, printed on every run.** The completeness scan reads
+`config/service/*.json` and literal `process.env.X` / `env.X` /
+`requireEnv('X')` in `src/`, `index.js` and `scripts/`. It cannot see dynamic
+access (`process.env[key]` — counted and reported, never guessed) or environment
+read inside an installed library, so a library-level variable such as
+`SECRETS_MASTER_KEY` is declared by hand until libraries export their own env
+schemas. The scan proves one direction only: what it CAN see is declared.
+
+A contract with no `env` block is skipped out loud by both consumers — a
+legitimate state until every repo adopts the declaration, and never silent.
+
 ---
 
 ## Runtime Directory Structure
@@ -103,7 +142,7 @@ The validator evaluates each service against cumulative implementation standards
 |-------|------|--------|-------|
 | **v1.0** | Base Service Standard | `conn-config/`, `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 | `@onlineapps/service-common` dep + `businessErrorHandler` in `src/app.js` | 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 |
 
 **Key properties:**
 - **Cumulative** — v1.2 requires v1.0 + v1.1 to also pass
@@ -118,13 +157,14 @@ const { ServiceStructureValidator } = require('@onlineapps/conn-orch-validator/s
 const validator = new ServiceStructureValidator('/path/to/service');
 const { level, details } = validator.determineStandardLevel();
 // level = 'v1.2', details = [{ level: 'v1.0', passed: true, checks: [...] }, ...]
+// A failing check may also carry `fix` — a ready-to-apply replacement line.
 
 // List all known levels
 ServiceStructureValidator.getStandardLevels();
 // [{ level: 'v1.0', name: 'Base Service Standard', since: '2025-06-01' }, ...]
 ```
 
-**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:** [Biz Service Canonical Shape — Implementation Standard Levels](/docs/biz/00-model/service-shape.md#implementation-standard-levels), [Biz Error Handling Contract](/docs/biz/70-contracts/error-handling.md)
 
 ## Related Documentation
 

package/TESTING_STRATEGY.md

@@ -65,7 +65,7 @@
 - ✅ ServiceWrapper E2E test suite created
 - ✅ Test infrastructure setup (Jest, Express for mock services)
 - ✅ Fixed message parsing from AMQP buffer to JSON
-- ✅ Created test-mq-flow.js for testing message flow
+- ✅ Created test-mq-flow.js for testing message flow (script removed 2026-08-26 — no consumer)
 - ✅ Fixed cookbook validation (added type field to steps)
 
 ### In Progress

package/docs/DESIGN.md

@@ -8,9 +8,8 @@ Validation framework for OA Drive microservices. Drives two flows:
    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.
+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
 [`operations.json`](../../../docs/biz/30-operations/registration-wire.md).
@@ -24,8 +23,10 @@ surface was removed together with the now-retired `ServiceValidator` /
   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.
+- **Fail-fast** — missing logger, missing operations.json: immediate throw.
+  `serviceUrl` is *not* among them: it fed the retired `/health` probe and
+  nothing reads it (ADR 0005). It is accepted and ignored so existing callers
+  keep working.
 
 ## Components
 
@@ -37,9 +38,13 @@ surface was removed together with the now-retired `ServiceValidator` /
 
 ### Production Validation
 
-- `ValidationOrchestrator` — 6-step pre-validation pipeline, emits proof
-- `ServiceReadinessValidator` — score-based readiness checks (operations /
-  endpoints / health / cookbook / registry)
+- `ValidationOrchestrator` — 5-step pre-validation pipeline (structure, config,
+  operations, cookbooks, connectors), emits proof
+- `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'
+  `tests/bootstrap/` suites. The `endpoints` and `health` checks are gone
+  (ADR 0005), and so is the `url` they took.
 - `ServiceStructureValidator` — config layout checks (config/service/*)
 - `ValidationProofGenerator` — fingerprint + codec helpers
 - `CookbookTestRunner` / `WorkflowTestRunner` — cookbook execution probes
@@ -48,7 +53,6 @@ surface was removed together with the now-retired `ServiceValidator` /
 ### Test Suite Helpers
 
 - `createServiceReadinessTests(options)` — Jest suite generator
-- `createPreValidationTests(options)` — Jest suite generator
 
 ## Integration Points
 
@@ -57,8 +61,11 @@ surface was removed together with the now-retired `ServiceValidator` /
   (30-day validity, invalidated by config fingerprint change — includes
   operations map, see
   [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.
+- The biz repos import `createServiceReadinessTests` from this package in their
+  `tests/bootstrap/service-readiness.test.js` (`converter`, `ingest`,
+  `hello-service`).
+- Pre-validation is driven by the `oa-biz-ci-gate run-prevalidation` subcommand,
+  not by a Jest suite generator.
 
 ## What We Test
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "3.3.2",
+  "version": "4.0.1",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "bin": {
@@ -24,15 +24,9 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/service-validator-core": "1.0.13",
-    "@onlineapps/runtime-config": "1.0.2",
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "amqplib": "^0.10.9",
-    "joi": "^17.9.0"
+    "@onlineapps/service-validator-core": "1.0.15"
   },
   "devDependencies": {
-    "express": "^4.18.0",
     "jest": "^29.5.0"
   },
   "engines": {