@onlineapps/conn-orch-validator 6.0.0 → 7.0.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 > ⚠ 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**.
 
+### BREAKING — standard level v1.1 "Multitenancy Standard" is removed (DÁVKA 88j)
+
+**Major.** `getStandardLevels()` now returns three levels, `v1.0, v1.2, v1.3`, and
+`determineStandardLevel().details` has one entry fewer. Anything indexing that
+array by position, or expecting a `tenant_context` check, reads something else now.
+
+Owner decision: `api/docs/governance/confirmations/service-shape-v11-retirement.md`.
+
+v1.1 held a single check, `tenant_context`, and it asserted nothing but the
+EXISTENCE of `wrapper.tenantContext` in `config/service/config.json`. Nothing
+reads that key: the wrapper runtime reads `cache`, `infrastructureGate`,
+`health`, `validation`, `mq`, `registry`, `monitoring`, `state`, `secrets` and
+`heartbeat`; `createTenantContextMiddleware` had had no caller since ADR 0005
+removed the HTTP surface (and was itself deleted on 2026-09-05,
+`docs/governance/confirmations/wrapper-tenant-middleware.md`); at the time,
+`service-wrapper/config/runtime-defaults.json` still supplied the key regardless
+of what a service declared. The gate was enforcing a
+dead declaration — `change-discipline.md` § *Removing something removes its
+declaration*.
+
+- **Removed** the level, not its checks. An empty level with `checks: () => []`
+  would pass for every service while asserting nothing, which is the false
+  guarantee `automation-gates.md` §5 names.
+- **The number is not reused and the gap stays.** v1.2 and v1.3 keep their names,
+  so a level recorded in an earlier proof still means what it meant. Cumulative
+  now reads *"v1.2 requires v1.0"*.
+- **A service is free to drop `wrapper.tenantContext`** and reach the same level
+  it reaches with it. Measured over `api_biz/*` (8 services, all of which still
+  declare the key): every verdict is `v1.3` before the change and `v1.3` after —
+  the removal takes a requirement away without moving a single live verdict.
+- The package's own conformant fixture (`tests/fixtures/v3-cookbook-service`)
+  drops the key in the same change; it carried it only to satisfy v1.1.
+
 ### BREAKING — a cookbook step spelling its identifier `id` is refused (DÁVKA 77 A3)
 
 `format.md` § Steps has banned `id` since v2.1; the code accepted it anyway, which

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,102 @@ 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. The **service version comes from the service `package.json`,
+  and from nowhere else** — the same single source of truth the readiness
+  section below describes. It used to be `config.service?.version ||
+  pkg.version`, which for a service carrying `"${npm_package_version}"` in
+  `config/service/config.json` hashed that literal and never consulted
+  package.json at all, so a version bump moved no bit of the fingerprint. A
+  missing, unparseable or version-less package.json now fails the run instead of
+  falling back.
+- **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.
+
+**"Can register" is not truthiness.** `canRegister` requires a `name`, an
+`operations` object, and a `version` matching the semver 2.0.0 grammar — the
+last one because the line below it compares that value against what the registry
+already holds, and comparing two strings that are not versions decides nothing.
+The string that made this measurable is `"${npm_package_version}"`: every biz
+`config/service/config.json` declares it under `service.version`, it is truthy,
+and the gate used to accept it (measured by BIZ-ingest). Each failing part
+contributes one `[Context] Problem - Expected/Fix` line to `checks.registry.errors`.
+
+The version a caller passes comes from the service **`package.json`**, never from
+`config.json`. That is the single source of truth the runtime uses:
+`ConfigLoader.loadServiceConfig()` overwrites `config.service.version` from
+package.json before `${VAR}` placeholders are resolved, so the config.json key
+never reaches a running service. `helpers/createServiceReadinessTests` reads
+package.json for exactly that reason.
+
+**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.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.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.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 |
+
+**v1.1 "Multitenancy Standard" was retired on 2026-09-04** (owner decision,
+`/docs/governance/confirmations/service-shape-v11-retirement.md`). Its only check
+asserted that `wrapper.tenantContext` was present in `config.json`, and nothing
+reads that key — the wrapper runtime never looks it up,
+`createTenantContextMiddleware` was deleted outright on 2026-09-05
+(`/docs/governance/confirmations/wrapper-tenant-middleware.md`), and
+`runtime-defaults.json` no longer carries the key either. The level is removed,
+not emptied: a level with no checks passes for everyone while asserting nothing
+(`automation-gates.md` §5). The number is not reused and the gap in the numbering
+stays, so a level recorded earlier still means what it meant.
 
 **Key properties:**
-- **Cumulative** — v1.2 requires v1.0 + v1.1 to also pass
+- **Cumulative** — each level requires every level listed above it (so v1.2
+  requires v1.0); the table is the authority, not the version number
 - **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 +241,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": "7.0.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

@@ -441,11 +441,22 @@ class CookbookTestRunner {
       // Synthesize an HTTP-like response so existing expect validators
       // continue to work (expect.status: 'error', expect.error.code, ...).
       const errorCode = handlerError.code || handlerError.name || 'HANDLER_ERROR';
-      const statusCode = typeof handlerError.statusCode === 'number'
-        ? handlerError.statusCode
+      // `status` is the platform's ONE name for the number a thrown error
+      // carries: `BusinessError` sets it, `ErrorMapper` reads it
+      // (@onlineapps/service-wrapper, src/ErrorMapper.js), and a service that
+      // throws its own class declares the same shape.
+      // @see api/docs/biz/70-contracts/error-handling.md §1
+      //
+      // No `statusCode || status` chain. The retired second name was read here
+      // and nowhere else, which is why three biz services mirrored the value
+      // under both names to satisfy this line; a fallback would keep both alive
+      // and let them drift. An error carrying no usable status is a 500 — the
+      // handler declared no outcome, so it gets the server fault it earned.
+      const status = typeof handlerError.status === 'number'
+        ? handlerError.status
         : 500;
       result.response = {
-        status: statusCode,
+        status,
         statusText: errorCode,
         data: { code: errorCode, message: handlerError.message }
       };

package/src/ServiceReadinessValidator.js

@@ -6,6 +6,19 @@ const CookbookTestUtils = require('./CookbookTestUtils');
 // error message lists them in.
 const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
 
+/**
+ * The semver 2.0.0 grammar, verbatim from semver.org's own published regular
+ * expression (anchored, no leading `v`, no surrounding whitespace, no leading
+ * zeroes in a numeric identifier).
+ *
+ * Written out rather than pulled from the `semver` package: this is the only
+ * version rule in the package, one anchored pattern expresses it completely,
+ * and a dependency added for a single `test()` call is a supply chain the gate
+ * does not need. If a second version rule ever appears here, that trade changes
+ * — and the change is then visible, because it is this comment that has to go.
+ */
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
 /**
  * ServiceReadinessValidator - Orchestrates complete service validation.
  *
@@ -311,16 +324,63 @@ class ServiceReadinessValidator {
   }
 
   /**
-   * Check registry compatibility
+   * Check registry compatibility.
+   *
+   * `canRegister` used to be `!!(name && version && operations)`. Truthiness is
+   * the wrong question about a version: the line below it compares this value
+   * against what the registry already holds, and a comparison between two
+   * strings that are not versions decides nothing. Measured (BIZ-ingest): every
+   * biz `config/service/config.json` declares
+   * `"service": { "version": "${npm_package_version}" }`, the placeholder was
+   * handed here unexpanded, and — being a non-empty string — it passed. The
+   * gate reported `canRegister: true` about a value that is not a version.
+   *
+   * The grammar is semver 2.0.0, checked here and nowhere else: this is the one
+   * place that decides `canRegister`. Callers supply the value (the `version`
+   * field of the service package.json, which is what ConfigLoader reads at
+   * runtime); they do not re-check it.
    */
   async checkRegistryCompatibility(service, registry) {
     try {
-      // Check if service can be registered
-      const canRegister = !!(
-        service.name &&
-        service.version &&
-        service.operations
-      );
+      const errors = [];
+
+      if (!service.name) {
+        errors.push(
+          '[ServiceReadinessValidator] Service name is missing - '
+          + 'validateReadiness() received no `name`. '
+          + 'Expected: the service name, e.g. biz-ingest. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      }
+
+      if (service.version === undefined || service.version === null) {
+        errors.push(
+          '[ServiceReadinessValidator] Service version is missing - '
+          + 'validateReadiness() received no `version`. '
+          + 'Expected: the `version` field of the service package.json, e.g. 1.4.2. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      } else if (!SEMVER_PATTERN.test(service.version)) {
+        errors.push(
+          '[ServiceReadinessValidator] Service version is not a semantic version - '
+          + `received "${service.version}". `
+          + 'Expected: MAJOR.MINOR.PATCH per semver 2.0.0, e.g. 1.4.2 or 1.4.2-rc.1. '
+          + 'Fix: pass the `version` field of the service package.json — the single source of '
+          + 'truth ConfigLoader reads at runtime. An unresolved "${...}" means the value came '
+          + 'from config.json instead, where the key is never expanded.'
+        );
+      }
+
+      if (!service.operations) {
+        errors.push(
+          '[ServiceReadinessValidator] Operations are missing - '
+          + 'validateReadiness() received no `operations`. '
+          + 'Expected: the flat operations object from config/service/operations.json. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      }
+
+      const canRegister = errors.length === 0;
 
       // Check if service operations match registry expectations
       const registeredService = registry.getService(service.name);
@@ -331,7 +391,8 @@ class ServiceReadinessValidator {
         passed: canRegister && compatible,
         canRegister,
         compatible,
-        existingVersion: registeredService?.version
+        existingVersion: registeredService?.version,
+        errors
       };
     } catch (error) {
       return {

package/src/ValidationOrchestrator.js

@@ -4,7 +4,13 @@ const fs = require('fs');
 const path = require('path');
 const { verifyConnectorContract } = require('./utils/connectorContract');
 const { normalizeEnvDeclaration, collectEnvCoverage, verifyEnvPresence } = require('./utils/envContract');
-const { ValidationProofCodec, ValidationProofVerifier } = require('@onlineapps/service-validator-core');
+// `ValidationProofVerifier` was destructured here alongside the codec and never
+// called. It verified a cached proof before booting; the proof cache was
+// removed (see validate()) and the verifier's last call site went with it,
+// leaving a binding whose only remaining effect was to tell a reader that this
+// class still checks proofs. `ValidationProofCodec` stays — finalizeResults()
+// encodes the proof it writes.
+const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
@@ -115,15 +121,72 @@ class ValidationOrchestrator {
 
 
 
+  /**
+   * Read and parse the service's package.json.
+   *
+   * It is the single source of truth for the service version — the same one
+   * validateConfig() names below, and the same one the biz pre-validation entry
+   * point (`src/utils/preValidation.js`) already reads. `config/service/config.json`
+   * cannot supply it: the wrapper's ConfigLoader
+   * (`api/shared/connector/service-wrapper/src/ConfigLoader.js`) assigns
+   * `config.service.version` from package.json unconditionally on every load, so
+   * the key in the file is dead — and where it is declared at all, biz services
+   * declare it as the unresolved literal `${npm_package_version}`.
+   *
+   * A missing, unreadable, unparseable or version-less package.json is a contract
+   * violation, not a computation hiccup, so it is raised here in full §5 shape
+   * rather than through calculateFingerprint()'s generic wrapper.
+   *
+   * @param {string} packageFile absolute path to the service's package.json
+   * @returns {object} the parsed package.json, `version` guaranteed non-empty
+   */
+  readServicePackageJson(packageFile) {
+    let raw;
+    try {
+      raw = fs.readFileSync(packageFile, 'utf8');
+    } catch (error) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json is unreadable - Expected: a readable ${packageFile}, `
+        + 'the single source of truth for the service version. '
+        + `Read failed with: ${error.code || error.message}. `
+        + 'Fix: point options.serviceRoot at the service directory that contains package.json.'
+      );
+    }
+
+    let pkg;
+    try {
+      pkg = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json is not valid JSON - Expected: parseable JSON at ${packageFile}. `
+        + `Parse failed with: ${error.message}. `
+        + 'Fix: repair the file.'
+      );
+    }
+
+    if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json has no version - Expected: a non-empty "version" string in ${packageFile}, `
+        + 'the single source of truth for the service version. '
+        + `Got: ${JSON.stringify(pkg.version)}. `
+        + 'Fix: set "version" in the service package.json.'
+      );
+    }
+
+    return pkg;
+  }
+
   /**
    * Calculate service fingerprint
    * Based on: version + operations.json + dependencies + config
    */
   async calculateFingerprint() {
+    const packageFile = path.join(this.serviceRoot, 'package.json');
+    const pkg = this.readServicePackageJson(packageFile);
+
     try {
       const configFile = path.join(this.configPath, 'config.json');
       const operationsFile = path.join(this.configPath, 'operations.json');
-      const packageFile = path.join(this.serviceRoot, 'package.json');
       const dockerFile = path.join(this.serviceRoot, 'Dockerfile');
       const dockerComposeFile = path.join(this.serviceRoot, 'docker-compose.yml');
       const envTemplateFile = path.join(this.serviceRoot, '..', '..', 'config', 'env-templates', `${path.basename(this.serviceRoot)}.env`);
@@ -134,7 +197,6 @@ class ValidationOrchestrator {
 
       const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
       const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
-      const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
 
       // Include infra file contents in fingerprint to detect changes in environment/setup
       const infra = {};
@@ -187,8 +249,21 @@ class ValidationOrchestrator {
       }
 
       // Generate fingerprint using FingerprintUtils (handles deep sorting)
+      //
+      // The version comes from package.json alone. It used to read
+      // `config.service?.version || pkg.version`, which hashed a value that was
+      // not a version at all: `config.service.version` is overwritten by the
+      // wrapper's ConfigLoader on every load (see readServicePackageJson above),
+      // and the services that declare it leave the unresolved literal
+      // `${npm_package_version}` in that key. The `||` then hid it — for those
+      // services the package.json branch was never reached, so publishing a new
+      // version of one did not move its fingerprint by one bit
+      // (package.json is otherwise represented here only by its @onlineapps
+      // dependency pins). config.json's own content is still hashed below, so
+      // editing that key is still detected — as a config change, which is what
+      // it is.
       const fingerprintData = {
-        serviceVersion: config.service?.version || pkg.version,
+        serviceVersion: pkg.version,
         operations: operations,
         dependencies: deps,
         config: config,

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,30 @@ 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';
+
+// The version comes from package.json, NEVER from config.json. ConfigLoader
+// (shared/connector/service-wrapper/src/ConfigLoader.js) assigns
+// `config.service.version` from package.json unconditionally on every load, and
+// does it BEFORE `${VAR}` placeholders are resolved — so `service.version` in
+// config.json never reaches a running service under any value, and reading it
+// here yielded the literal string `${npm_package_version}`.
+const serviceVersion = JSON.parse(
+  fs.readFileSync(path.join(serviceRoot, 'package.json'), 'utf-8')
+).version;
 ```
 
+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 +153,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 +196,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*

package/src/helpers/createServiceReadinessTests.js

@@ -84,9 +84,22 @@ function createServiceReadinessTests(testsDir, options = {}) {
   const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
 
-  // Extract metadata from config
   const serviceName = config.service.name;
-  const serviceVersion = config.service.version;
+
+  // The version comes from package.json, never from config.json — the same
+  // single source of truth the runtime uses:
+  //
+  //   shared/connector/service-wrapper/src/ConfigLoader.js:239
+  //     config.service.version = this.loadPackageVersion(basePath);
+  //
+  // That assignment is unconditional and happens BEFORE `${VAR}` placeholders
+  // are resolved, so `service.version` in config.json never reaches a running
+  // service under any value. Reading it here was reading a dead key, and the
+  // value it yielded was the literal string `${npm_package_version}`: the
+  // placeholder that no expansion pass ever touches, handed to
+  // ServiceReadinessValidator, which used to accept it for being truthy.
+  const packagePath = path.join(serviceRoot, 'package.json');
+  const serviceVersion = JSON.parse(fs.readFileSync(packagePath, 'utf-8')).version;
 
   describe(`${serviceName} Service Readiness @integration`, () => {
     test('service passes readiness validation', async () => {

package/src/utils/deployContract.js

@@ -331,6 +331,77 @@ function isCommentLine(line) {
   return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
 }
 
+/**
+ * The other half of the same distinction. A comment is prose because of WHERE
+ * it sits; an error message is prose because of WHAT IT SAYS.
+ *
+ * "Inside quotes" alone is NOT the test, and must never become it: a query is
+ * a string too, and a query is exactly what reaches a database —
+ * `SELECT 1 FROM t WHERE tenant_id = 100` has to keep failing. What separates
+ * the two is the verb. Prose makes a CLAIM about the identifier ("workspace_id
+ * = 0 IS NOT a value"); code assigns a VALUE to it, and nothing follows the
+ * number but syntax.
+ *
+ * So the permit is granted only when the number is followed, inside the same
+ * string literal, by a finite verb from the closed list below. Everything else
+ * — end of string, `,`, `)`, ` AND `, ` order by ` — stays reported. The list
+ * is deliberately short and enumerated rather than clever: a gate whose verdict
+ * cannot be predicted from reading it is not a gate (`automation-gates.md` §1).
+ *
+ * Both conditions fail CLOSED. A string that spans several lines looks to this
+ * line-local scanner like no string at all, so its literal keeps its report.
+ */
+const PROSE_PREDICATE =
+  /^[\s,;:—-]*\b(is|are|was|were|has|have|had|means|meant|carries|carry|cannot|must|never|does|do|would|will|remains|stays)\b/i;
+
+/**
+ * The end offset of the CLOSED string literal containing `index`, or -1 when
+ * that position is code. Line-local and escape-aware; a quote opened on an
+ * earlier line is invisible here, which is the safe direction (no permit).
+ */
+function enclosingStringEnd(line, index) {
+  let quote = null;
+  let start = -1;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (quote !== null && ch === '\\') { i += 1; continue; }
+    if (quote === null) {
+      if (ch === "'" || ch === '"' || ch === '`') { quote = ch; start = i; }
+    } else if (ch === quote) {
+      if (index > start && index < i) return i;
+      quote = null;
+      start = -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * True when the literal at `index` is quoted inside an English sentence that
+ * talks ABOUT the identifier, rather than handing it a value.
+ */
+function isProseLiteral(line, index, matchText) {
+  const end = enclosingStringEnd(line, index);
+  if (end === -1) return false;
+  return PROSE_PREDICATE.test(line.slice(index + matchText.length, end));
+}
+
+/**
+ * A tenant / workspace identity frozen into this line of executable code.
+ *
+ * One rail for both scan sites (src+scripts, and the shared test-namespace
+ * module), so the two permits — comment, prose — cannot drift apart.
+ */
+function freezesNamespaceIdentity(line) {
+  if (isCommentLine(line)) return false;
+  for (const pattern of [LITERAL_NAMESPACE, LITERAL_NAMESPACE_CONST]) {
+    const match = pattern.exec(line);
+    if (!match) continue;
+    if (!isProseLiteral(line, match.index, match[0])) return true;
+  }
+  return false;
+}
+
 function walkFiles(dir, base, out) {
   let entries;
   try {
@@ -384,8 +455,7 @@ function checkNamespaceLiterals(serviceRoot, add) {
       if (text === null) continue;
       const lines = text.split('\n');
       for (let i = 0; i < lines.length; i += 1) {
-        if (isCommentLine(lines[i])) continue;
-        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        if (!freezesNamespaceIdentity(lines[i])) continue;
         add('R8', `${file.relative}:${i + 1} freezes a tenant / workspace id into code:\n`
           + `       ${lines[i].trim()}\n`
           + '       Fix: take it from ctx (handlers), from a CLI argument (scripts),\n'
@@ -409,8 +479,7 @@ function checkIntegrationNamespaceSource(serviceRoot, add) {
     if (isNamespaceModule(file.relative)) {
       const lines = text.split('\n');
       for (let i = 0; i < lines.length; i += 1) {
-        if (isCommentLine(lines[i])) continue;
-        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        if (!freezesNamespaceIdentity(lines[i])) continue;
         add('R8', `${file.relative}:${i + 1} freezes the test namespace into a literal:\n`
           + `       ${lines[i].trim()}\n`
           + '       This module exists so the namespace has one source; that source must\n'

package/src/validators/ServiceStructureValidator.js

@@ -4,7 +4,10 @@
  * Validates that a business service has correct directory structure,
  * configuration files, and follows OA Drive standards.
  *
- * Each standard level is cumulative — v1.2 requires all checks from v1.0 + v1.1 + v1.2.
+ * Each standard level is cumulative — a level requires all checks from every level
+ * declared before it in STANDARD_LEVELS, in that order. The list is the authority,
+ * not the version number: v1.1 was retired on 2026-09-04 and its number is not
+ * reused, so today "v1.2" means v1.0 + v1.2.
  * Older validator versions naturally support fewer levels (they don't know about newer ones).
  *
  * @module validators/ServiceStructureValidator
@@ -268,24 +271,21 @@ const STANDARD_LEVELS = [
       return results;
     }
   },
-  {
-    level: 'v1.1',
-    name: 'Multitenancy Standard',
-    since: '2026-03-01',
-    checks: (root) => {
-      const configRaw = readConfigFile(root, 'config.json');
-      let hasTenantContext = false;
-      if (configRaw) {
-        try {
-          const cfg = JSON.parse(configRaw);
-          hasTenantContext = cfg.wrapper?.tenantContext !== undefined;
-        } catch { /* invalid JSON */ }
-      }
-      return [
-        { passed: hasTenantContext, id: 'tenant_context', message: 'wrapper.tenantContext configured in config.json' }
-      ];
-    }
-  },
+  // v1.1 "Multitenancy Standard" was retired on 2026-09-04 (owner decision,
+  // api/docs/governance/confirmations/service-shape-v11-retirement.md). Its single
+  // check `tenant_context` asserted only that `wrapper.tenantContext` EXISTED in
+  // config.json. Nothing reads that key: the wrapper runtime reads cache,
+  // infrastructureGate, health, validation, mq, registry, monitoring, state,
+  // secrets and heartbeat — not tenantContext; `createTenantContextMiddleware`
+  // was deleted on 2026-09-05 together with the runtime-defaults key
+  // (docs/governance/confirmations/wrapper-tenant-middleware.md). A
+  // level enforcing a dead declaration is the false guarantee automation-gates.md
+  // §5 names, so the level is GONE rather than emptied — an empty level would
+  // pass for every service while asserting nothing.
+  //
+  // The number is deliberately not reused and the gap is not closed up: v1.2 and
+  // v1.3 keep their names so that a level recorded in an older proof still means
+  // what it meant. Cumulative now reads "v1.2 requires v1.0".
   {
     level: 'v1.2',
     name: 'Business Error Handling Standard',