@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/README.md

@@ -195,14 +195,17 @@ What Tier-1 adds is the SCOPE, and only the scope
 A literal `{{…}}` is the right outcome for a value that is missing at that
 moment — a step that has not run yet, or one that failed. It is the wrong
 outcome for an expression no run could ever resolve, because then a green Tier-1
-certifies a recipe production does not accept. Two such shapes are refused
-BEFORE any step of the cookbook runs, each with its own `Fix:`:
+certifies a recipe production does not accept. These shapes are refused
+BEFORE any step of the cookbook runs, each with its own `Fix:`. The helper call
+is the runner's own refusal; the step references are
+`@onlineapps/cookbook-core` `validateCookbook`'s, which the runner runs first and
+holds no copy of (d.980):
 
 | Written in a step's `input` | Tier-1 | Production |
 |---|---|---|
 | `{{webalizeString(…)}}`, `{{string2file(…)}}` — any `name(…)` | refused: `Step <id> input calls the template helper "<name>"` | the orchestrator evaluates it through its helper registry, and throws on a name that registry does not carry |
-| `{{steps.<id>.…}}` naming no step THIS cookbook defines (`{{steps.0.…}}` included — `0` is a name no recipe declares) | refused: `Step <id> references an undefined step` | 400 `Invalid cookbook references` at submission |
-| `depends_on` naming no step this cookbook defines | refused: `Step <id> depends on an undefined step` | — |
+| `{{steps.<id>.…}}` naming no step THIS cookbook defines (`{{steps.0.…}}` included — `0` is a name no recipe declares) | refused (cookbook-core): `Step references that cannot resolve at run time - <id>.input: … - unknown step '<x>'` (positional: `… never by position`) | 400 `Invalid cookbook references` at submission |
+| `depends_on` naming no step this cookbook defines | refused (cookbook-core): `Step '<id>' depends on non-existent step_id '<x>'` | — |
 
 The helper registry is absent from the runner on purpose: a helper reaches its
 own runtime (`@onlineapps/content-resolver`, files, storage), which is not what a
@@ -277,15 +280,18 @@ schema name is refused rather than escaped — no platform name carries one.
 
 ### Running the live-database suites
 
-Two suites of this package measure what a **real** MariaDB does with the SQL the
-package builds — `tests/unit/setupDatabaseLive.integration.test.js` (what
-`ci:gate:setup` leaves in the schema) and `tests/unit/dbCiAccount.integration.test.js`
-(whether the grants above are enough, and still not too much). They are part of
-`npm run test:unit`, and in CI they have a job with a database of its own,
-`test-validator-db` (owner decision
+The live-database suites of this package measure what a **real** MariaDB does
+with the SQL the package builds: what `ci:gate:setup` leaves in the schema,
+whether the account `setup-db-account` creates is granted enough — and still not
+too much — and how far the production grant of that account reaches. They are
+the suites that require `tests/helpers/liveDatabase.js`, and the list of them is
+the `script` of the job `test-validator-db` in `api/.gitlab-ci.yml`; this
+sentence does not keep a second copy of it. They are part of
+`npm run test:unit`, and in CI that job gives them a database of its own (owner
+decision
 [`ci-validator-db-job` 001](../../../docs/governance/confirmations/ci-validator-db-job.md)).
 
-Neither suite looks for a database. It is **declared**, under the names this
+No such suite looks for a database. It is **declared**, under the names this
 package's own CLI reads:
 
 | Variable | What it is |
@@ -310,9 +316,14 @@ DB_HOST=gen_mariadb10.5 DB_PORT=3306 \
 CI_DB_ROOT_USER=root \
 CI_DB_ROOT_PASSWORD="$(grep '^MARIADB_ROOT_PASSWORD=' ../../../config/env-active/gen-db.env | cut -d= -f2-)" \
 DB_DOCKER_NETWORK=gendb-network \
-npx jest tests/unit/setupDatabaseLive.integration.test.js tests/unit/dbCiAccount.integration.test.js
+npx jest $(grep -rl 'helpers/liveDatabase' tests/unit)
 ```
 
+Which suites that selects is not typed here either: it is the requirement of the
+helper, so a suite that joins them is run by this block unedited, and
+`npx jest --listTests $(grep -rl 'helpers/liveDatabase' tests/unit)` says which
+files the next run will take before it takes them.
+
 The run prints which server it measured, or why it measured none — that line is
 what tells a green suite that looked from a green suite that did not.
 
@@ -735,7 +746,7 @@ the three already had an owner, so no second notation was introduced for them
 
 | file | row | decided by |
 |---|---|---|
-| `operations.json` | `C-OPS` | `service-validator-core` `validateOperationsSchema` — the mirror of the fifteen rules the Registry applies on registration |
+| `operations.json` | `C-OPS` | two definitions, neither of them in this row. What each OPERATION must be: `service-validator-core` `validateOperationsSchema` — the mirror of the fifteen rules the Registry applies on registration, reached through `src/utils/operationsRules.js`. What the DOCUMENT must be (`schema_version: "3.0"`, at least one operation declared, and — for the two rails that generate a cookbook from it — `input`/`output` declared with `description` warned about): `src/utils/operationsDocumentRules.js`, which is deliberately NOT in the core — the Registry receives `doc.operations` alone, never the file, and generates no cookbook, so it has a rule about none of them. The row asks the first two; boot step 4 and the readiness score ask all three. Until d.465 this row said the first half and did not do it, while three other rails each restated a different subset of the rules from memory; until d.465b an empty operations map had four answers across those rails (error · warning · silence · finding) and a missing `schema_version` had none |
 | `integration-contract.json` | `C-CONTRACT` | `utils/bizCiGateContract.js` — the validator the CI gate already runs over this document, so the gate and the table can never disagree about it |
 | `config.json` | `C-SERVICE` | `src/manifest/checks/serviceConfig.js`, which had no owner before |
 
@@ -771,6 +782,39 @@ once, in `DEAD_KEYS` (`src/manifest/checks/serviceConfig.js`), and the manifest
 `why` is held equal to that list by its own test — so this paragraph names the class,
 never the count. The fix is always the same sentence — delete the key.
 
+**`C-CI-CONNECTOR-ENV`** asks the other half of the connector question. `C-CONNECTORS`
+above compares two declarations with each other; this row compares them with the ONE
+environment they are exercised in every day. Measured 2026-09-18: three `emailer` tests
+failed in CI on `[RuntimeConfig] Missing environment variable - MINIO_USE_SSL`, a name no
+line of the service reads — `@onlineapps/conn-base-storage` resolves it, `required: true`,
+with no default — so `ci:gate:contract` could not see it (`node_modules` is deliberately
+outside its scan, § Environment contract) and `ci:gate:env` emits six `OA_CI_*` names and
+measures nothing. The same suite passes locally, because the one-shot runner loads
+`config/env-templates/shared.env` through `env_file` and that generated copy carries the
+key; the job's `variables:` is the SECOND delivery of the same set, copied by hand in eight
+repositories, and nothing compared it with the first.
+
+The row is keyed by the service's own `requiredConnectors` and by the names the connector's
+library resolves **without a default** — `CONNECTORS` in `src/utils/connectorContract.js`,
+measured against that library's schema, so nothing is copied into the manifest. It is
+deliberately NOT keyed by `required: true` in a library schema: the resolver's priority is
+explicit config → env → default, so that flag is conditional, and four families satisfy it
+while being no gap at all (`REDIS_HOST`/`REDIS_PORT`, which the wrapper passes explicitly;
+`SERVICE_NAME` in `infrastructure-tools`, on the infra path;
+`INFRA_REPORT_SMTP_REQUIRE_TLS`, read only for a fallback transport;
+`LOG_MAX_SIZE_BYTES`/`LOG_MAX_FILES`, delegated to the file sink). A gate on that flag would
+have reported findings nobody could fix on its first day (`automation-gates.md` §3).
+
+Like `D-DB-CI-ACCOUNT` it reads only OUTSIDE the `oa-ci v1` block, which is `G-CI`'s, and
+only the `variables:` of the job the row names — the MinIO sidecar's own `variables:`, two
+levels deeper, is that container's environment and not the job's. It asks WHICH names that
+job sets and deliberately not WHETHER a repository runs one, because "add a test job" is
+another fix and one row with two fixes is two mechanisms under one name. It cannot see
+GitLab's project-level variables, which live outside the repository by design, so it
+measures only names with a platform value in `api/config/shared-env.json` — never a secret.
+Owner decision
+[`biz-service-manifest`](../../../docs/governance/confirmations/biz-service-manifest.md) 013.
+
 `service.url` is the one entry carrying a **date**: it is dead from wrapper **8.0.0**,
 not today. The published 7.0.0 still throws
 `Missing configuration - service.url is required`, so the key travels WITH the pin, which
@@ -1003,12 +1047,18 @@ becomes an artefact and therefore never reaches a service.
 npx oa-validate --library ../../logger-contract      # one package
 npx oa-validate --library --all                      # every package the uniform finds
 npx oa-validate --library --all --workspace /path/to/workspace --json
+npx oa-validate --library ../../logger-contract --as-version 1.2.4   # judged as the version being published
 ```
 
 One table (`id · category · where · what · fix`), the `doc` pointer of every reported
 row, exit `0` / `1`; `2` when the run could not start. `--library` with neither a
 package directory nor `--all` is a usage error — nothing is guessed.
 
+`--as-version <X.Y.Z>` (one package only) is the question a publish dry run asks: the
+rows that judge a version — `L-CHANGELOG` — judge the version about to be written, not
+the one `package.json` still carries, and the finding names both. Without it the run
+audits the tree as it stands (d.1040).
+
 **Who wears the uniform** is discovery, not a list: `api/shared/**/package.json` minus
 `**/node_modules/**` and `**/tests/fixtures/**`, bound to `api/config/libraries.json`.
 A package the SSOT does not know, and a name in the SSOT with no package, are both
@@ -1048,7 +1098,14 @@ the raw file text, so a module documenting the duty it obeys — "this module re
 
 `L-PACK-TESTS` measures the **effect**, not the file: eight packages keep `tests/` out of
 the tarball with a `files` allowlist and no `.npmignore` at all, and a row checking for
-the file would report eight packages that are already right.
+the file would report eight packages that are already right. An allowlist entry reaches
+`tests/` when its first segment matches the name — `tests`, `*`, or `**` — so
+`["**/*.js"]` is a finding too. The row is about the package's own tier at its root: a
+`tests/` under `templates/**` is template content (this package ships
+`templates/business-service/tests/**` for `oa-sync-template --new`) and is never a finding.
+An ignore file is read the way npm walks it, negations included: `/tests/` followed by
+`!tests/**` ships the tier and is a finding naming the `!` line (d.1006); the reproduction is
+held against `npm pack --dry-run --json` by `libraryPackTests.npmPack.integration.test.js`.
 
 **What is deliberately NOT a row** is written down as such, in the manifest's `guidance`
 block, with the reason and the decision it rests on — a duty nothing can decide is
@@ -1221,12 +1278,41 @@ Rewrites the files the manifest declares in the classes `identical`, `generated`
 at — one definition, read twice. With no paths it plans every such row. Files of the `own`
 class — `src/**`, `tests/**`, the content of `docs/**` — are never written.
 
+**One run is the whole sync of a service.** "Bring this repository into line with
+everything the uniform generates" is `npx oa-sync-template --target .`, and nothing else:
+every generated row of the service uniform is a line of that run, `README.md` (row
+`G-README`) and `config/env-templates/shared.env` (row `G-SHARED-ENV`) included. What is
+NOT in it is `template` and `docs-region`, because their bearer is not a service —
+`api/templates/business-service` and the `api/docs/**` tree are other directories with
+other owners.
+
+Until d.710 the run's row set was the manifest's `files` section, and `G-SHARED-ENV` is
+filed under `config`, where the manifest reports about a service's configuration. So
+`oa-validate` measured `shared.env` and the sync wrote nothing: a repository could finish
+the sync and be reported `NOT DEPLOYABLE` by the very manifest the sync reads (measured
+2026-09-20 over a copy of `api_biz/hello` — `NOT DEPLOYABLE — 1 finding(s)` immediately
+after a full bare run). Instruction 3 of the library cascade asked eight repositories to
+"sync every row", which was in fact four commands each of them assembled for itself, and
+BIZ-ingest escalated on 2026-09-18 that the bare run does not carry that row. A row now
+says what it IS — `"class": "generated"` — wherever the manifest reports it from, and the
+sync reads that declaration rather than a section's name. A row joins by SAYING so: `own`
+and `forbidden` cannot drift in, and neither can a future row of any other section.
+
+`G-SHARED-ENV` renders through `src/sync/sharedEnv.js`, the module that owns the shared
+key set, in the same expression its own CHECK evaluates — so the bare run, the `shared-env`
+subcommand and `oa-validate` cannot produce three opinions of one file. The subcommand
+stays, and not as a convenience: `api/` itself and the business-service template carry
+`shared.env` too, and neither is a service root the bare run could be pointed at.
+
 **No workspace is required of the run itself** — only of the ROWS that read a workspace
 file, and since d.229 most of them read a file this package carries. The predicate is the
 one the manifest run uses (`rowNeedsWorkspace`), so the `fix` command of `F-INIT`,
 `F-JEST` and `F-RUNNER` can be typed where their finding is now raised: inside the service
 image. A row that does need one is printed `NOT RUN` by name with the `--workspace` fix,
-never skipped in silence.
+never skipped in silence. Inside a service container that is exactly one line, and it names
+the row and the file: `NOT RUN G-SHARED-ENV config/env-templates/shared.env — the workspace
+root is not reachable, so api/config/shared-env.json cannot be read. Fix: …` — the shared
+key set has a platform file for an owner, so no pinned copy can answer for it.
 
 A row the manifest does not make renderable is **not a row of this run**. Today that is
 `G-PROD-IMAGE` and `G-SETUP`: they declare no `from:` reference, so nothing says what
@@ -1241,8 +1327,11 @@ choosing a position among somebody's own install steps; an installation document
 section, where writing one would mean rewriting somebody's prose — is printed `BLOCKED`
 and exits 1.
 
-Three rows need more than a splice, and the module that owns their CHECK renders them, so
-the generator cannot produce a file its own check rejects:
+Where a row needs more than a splice, the module that owns its CHECK renders it, so the
+generator cannot produce a file its own check rejects (`src/sync/uniformFiles.js` §
+`RENDERERS` is the whole list; a count written here would be a hand-maintained number,
+which `doc-code-binding.md` §1 forbids — it was wrong by one before d.710 and by two
+after):
 
 * **`F-RUNNER`** — the `oa-test-runner v1` block is the template's, except for `build`,
   `env_file` and `networks`, which the same row requires to equal the service the runner
@@ -1279,6 +1368,11 @@ the generator cannot produce a file its own check rejects:
   one is never rewritten, and a missing section is `BLOCKED` with the heading named. That
   a document is absent at all stays `G-SETUP`'s finding, through the installation
   contract's `SETUP_DOCS`, so one defect keeps one owner.
+* **`G-SHARED-ENV`** — `config/env-templates/shared.env`, the whole file, rendered by
+  `src/sync/sharedEnv.js` from the referenced document `api/config/shared-env.json`. The
+  row's `from:` names the owner and this module knows no key, no format and no path to it.
+  It is the one row of the run whose owner is a workspace file, so it is also the one that
+  can report `NOT RUN` in a detached checkout.
 
 `--check` writes nothing and exits 1, naming the first line that differs and what the run
 would put there — both sides, because one of them alone lies about half the runs: an
@@ -1301,7 +1395,7 @@ differs and on a file the packaged template has no source for.
 
 ### `oa-sync-template shared-env`
 
-`config/env-templates/shared.env` is generated, never edited, never edited. The platform env manifest
+`config/env-templates/shared.env` is generated, never edited. The platform env manifest
 `api/config/shared-env.json` owns the shared key set — name, template value, why the
 platform shares it — and every bearer's copy is rendered from it, so a service can only
 add keys of its own in `service.env`.
@@ -1310,8 +1404,21 @@ add keys of its own in `service.env`.
 npx oa-sync-template shared-env --target <bearer dir> [--workspace <root>] [--check]
 ```
 
+Neither path in that sentence is written into this command. Since d.710c both come off
+the manifest row `G-SHARED-ENV`: `row.from` says which file owns the content, `row.path`
+says where the bearer keeps it, and the command reads the reference the same way every
+other row is read. It used to build the SSOT's location itself, from the workspace marker,
+beside the row that declares the same file to `oa-validate` — two declarations of one
+location, of which only one could be right the day it moved.
+
 `--target` is the bearer: a service root, `api/` itself, or the business-service
-template; `--workspace` is the directory holding `api/` and `api_biz/`, found upwards
+template. For a SERVICE this is not the only entrance and has not been since d.710: the
+bare run writes the same file through row `G-SHARED-ENV`, calling this same renderer on
+the same referenced document, so a service is synced by one command and the two entrances
+cannot disagree. The subcommand is what the other two bearers have, because neither `api/`
+nor the template is a service root.
+
+`--workspace` is the directory holding `api/` and `api_biz/`, found upwards
 from the target when it is not given. `--check` writes nothing and exits 1 with the diff
 when the file on disk is not what the manifest renders; a run that cannot start at all
 exits 2. There is no flag pointing the run at another manifest — the shared key set has

package/manifests/biz-service.manifest.json

@@ -397,7 +397,7 @@
         "path": "config/service/operations.json",
         "severity": "boot",
         "owner": "BIZ-general",
-        "why": "the v3 dispatch table; the per-operation rules (handler, bundle_scope, forbidden v2 fields) are step 4 of the boot validation, which this row does not repeat",
+        "why": "the v3 dispatch table; the per-operation rules are asked of @onlineapps/service-validator-core, the one definition of what the Registry refuses on registration, so this row and boot step 4 can never disagree about them",
         "fix": "declare the service's operations in config/service/operations.json",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a72"
       },
@@ -420,6 +420,18 @@
         "fix": "make the two declarations agree: set requiredConnectors.<connector> to what the service really needs, or add the wrapper section that configures it / remove the one nothing requires",
         "doc": "api/docs/governance/confirmations/connector-contract-check.md"
       },
+      {
+        "id": "C-CI-CONNECTOR-ENV",
+        "check": "ci-connector-env",
+        "path": ".gitlab-ci.yml",
+        "block": "oa-ci v1",
+        "job": "test",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "the row above measures whether the two declarations agree; this one measures whether the ONE environment they are exercised in every day carries what they need. Measured 2026-09-18: three emailer tests failed in CI on \"[RuntimeConfig] Missing environment variable - MINIO_USE_SSL\", a name no line of the service reads — @onlineapps/conn-base-storage resolves it, required:true, with no default — so ci:gate:contract could not see it (node_modules is deliberately outside its scan) and ci:gate:env emits six OA_CI_* names and measures nothing. The same suite passes locally, because the one-shot runner loads config/env-templates/shared.env through env_file and that generated copy carries the key; the CI job's variables: is the SECOND delivery of the same set, copied by hand in eight repositories, and nothing compared it with the first. The row is keyed by the service's own requiredConnectors declaration and by the names the connector's library resolves without a default (CONNECTORS in utils/connectorContract.js) — never by required:true in a library schema, which is conditional and holds for four families of keys that are no gap at all. It reads the variables: of the test job OUTSIDE the oa-ci v1 block, which is G-CI's, and asks WHICH names that job sets, deliberately not WHETHER a repository runs one. It cannot see GitLab's project-level variables, so it measures only names with a platform value in api/config/shared-env.json, which belong in the file",
+        "fix": "add the missing name to the variables: block of the test job in .gitlab-ci.yml, below the oa-ci v1 block — with the value config/env-templates/shared.env declares for that key where the platform owns one, and with this job's own sidecar value where it does not",
+        "doc": "api/docs/governance/confirmations/biz-service-manifest.md"
+      },
       {
         "id": "C-SERVICE-DEAD",
         "check": "config-dead-keys",
@@ -441,13 +453,14 @@
       },
       {
         "id": "G-SHARED-ENV",
+        "class": "generated",
         "check": "shared-env-generated",
         "path": "config/env-templates/shared.env",
         "from": { "path": "api/config/shared-env.json", "text": true },
         "severity": "deploy",
         "owner": "BIZ-general",
         "why": "the shared key set is one fact with one owner; measured on 2026-09-09, none of the nine copies matched the platform file and one key existed in no copy at all. The owner is api/config/shared-env.json and this row renders from it with the renderer the sync command writes with, so a service cannot be synced and reported drifted in the same hour; a run that cannot REACH the workspace says NOT RUN and names the command, because a render published with this package answers about the day it was published, not about the SSOT; a run that does reach it and finds no api/config/shared-env.json in the api checkout stops instead - a missing SSOT in a workspace the run can read is a finding and never a NOT RUN (automation-gates.md §5), and the message names the checkout to update and the api ref a CI job has to move",
-        "fix": "npx oa-sync-template shared-env --target .",
+        "fix": "npx oa-sync-template --target .",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a718"
       },
       {

package/manifests/library.manifest.json

@@ -174,12 +174,12 @@
         },
         {
           "id": "L-CHANGELOG",
-          "check": "file-present",
+          "check": "library-changelog-entry",
           "path": "CHANGELOG.md",
           "severity": "publish",
           "owner": "BIZ-general",
           "why": "a published version whose change nobody wrote down is a version nobody can reason about afterwards",
-          "fix": "add CHANGELOG.md with an entry for the version being published",
+          "fix": "write the entry for the version being published — the one in package.json, or the one --as-version names on a publish dry run — under \"## [<version>]\" in CHANGELOG.md — a heading with nothing under it does not count; a pin-only release says which pin moved",
           "doc": "api/docs/guides/library-publishing-process.md"
         },
         {
@@ -187,8 +187,8 @@
           "check": "library-readme",
           "severity": "publish",
           "owner": "BIZ-general",
-          "why": "a README that cannot say which fact class it owns has no reason to exist, and nobody can tell a live one from a stale one",
-          "fix": "give README.md the node header - \"> Owns: <the fact class this file is the single owner of>\" and \"> Status: current|draft|archived\"",
+          "why": "a README that cannot say which fact class it owns has no reason to exist, nobody can tell a live one from a stale one, and a version copied into it by hand goes stale without anyone noticing",
+          "fix": "give README.md the node header - \"> Owns: <the fact class this file is the single owner of>\" and \"> Status: current|draft|archived\" - and delete any hand-written package version from it; package.json owns the version",
           "doc": "api/docs/standards/INFRA-DOC-STANDARD.md"
         },
         {

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "12.2.0",
+  "version": "13.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"
   },
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./manifests/*": "./manifests/*",
+    "./templates/*": "./templates/*",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "oa-biz-ci-gate": "src/cli/biz-ci-gate.js",
     "oa-lint-scripts": "src/cli/oa-lint-scripts.js",
@@ -28,9 +34,11 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/cookbook-core": "6.0.0",
+    "@onlineapps/cookbook-core": "7.0.0",
+    "@onlineapps/error-handler-core": "4.0.0",
+    "@onlineapps/handler-contract": "1.0.0",
     "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/service-validator-core": "2.1.0"
+    "@onlineapps/service-validator-core": "2.2.0"
   },
   "devDependencies": {
     "jest": "^29.5.0"