@onlineapps/conn-orch-validator 8.1.0 → 9.0.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [9.0.0] — 2026-09-15
+
+### Removed — šablona už nenese job `verify-installation-contract` (d.470)
+
+Blok `oa-ci v1` v `templates/business-service/.gitlab-ci.yml` deklaroval job, který pouštěl
+`sh scripts/verify-installation-docs-sql-contract.sh`. Šablona ten skript **nikdy nenesla**
+(`templates/business-service/scripts/` = jen `verify-deploy-uniform.sh`) — osm biz repozitářů mělo
+každý vlastní kopii a mapa vydání d.320 ruší všech osm. Job v bloku tedy sliboval kontrolu, kterou
+nově nascaffoldovaná služba nemůže provést (`automation-gates.md` §5).
+
+Norma se nikam neztratila, jen má jednu kolej místo dvou: `install-contract` je ve validatoru
+(`src/utils/installContract.js`) a manifest ji vymáhá řádky `G-SETUP`, `D-DB-PACKAGE` a
+`D-DB-HEADERS`, které běží v uniformě před SSH krokem téhož deploy jobu (konfirmace
+`biz-service-manifest` 008) — a jako podpříkaz `biz-ci-gate verify-install-contract`.
+
+### Changed — test job šablony nedělá `REGISTRY_URL` (d.470)
+
+`test:` (mimo značky, výchozí job nové služby) deklaroval `REGISTRY_URL: "http://localhost:33100"`.
+Nic, co ten job spouští, ho nečte: `test:ci` je `jest`, `jest.config.js` matchuje
+`**/tests/**/*.test.js` a jediný test šablony požaduje `src/handlers/v3/echo.js`. Klíč byl HTTP
+adresou registru pro `getService()`; konfirmace `biz-discovery-redis` 001 přesunula čtení na Redis
+projekci a `725b25c2` HTTP volání odstranil. Čtyři otázky před rušením deklarace jsou zodpovězeny
+v `api/docs/governance/confirmations/declaration-removal.md` 001. Deklarace klíče v
+`config/env-templates/shared.env` se netýká — tu vlastní `api/config/shared-env.json`.
+
+### Changed — deploy job migruje jen tam, kde fáze 1 proběhla (d.477)
+
+Krok migrací dělal `touch "$TRACKER"` a poté aplikoval vše, co tracker neznal — na boxu, kde
+fáze 1 nikdy neběžela, by tak deploy aplikoval **celou řadu sám**. Konfirmace
+`api/docs/governance/confirmations/db-migrations-first-deploy.md` 001 dělí práci na dvě fáze a
+první z nich (schéma, účet a první běh téhož běžce ručně podle runbooku) nechává člověku.
+
+Tracker `config/runtime/applied-migrations-<schema>.txt` je proto od teď **precondition**, ne
+výstup: chybí-li, job končí fail-fast hláškou `[deploy] Migrations tracker <cesta> missing -
+phase 1 … has not run on this box` a jmenuje runbook `api/docs/setup/INSTALL.md`. Žádný `touch`,
+žádné `mkdir` — krok nezakládá nic, stejně jako nezakládá schéma ani účet. Prázdný tracker
+zůstává platným stavem (fáze 1 bez přenesených souborů). `docs/80-setup/INSTALL.md` šablony
+§ Migrations at deploy time to říká třetí odrážkou.
+
 ## [8.1.0] — 2026-09-15
 
 ### Changed — deploy job šablony aplikuje migrace DB mezi `pull` a `up` (d.421)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "8.1.0",
+  "version": "9.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"
@@ -28,8 +28,8 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/logger-contract": "1.3.0",
-    "@onlineapps/service-validator-core": "2.0.0"
+    "@onlineapps/logger-contract": "2.0.0",
+    "@onlineapps/service-validator-core": "2.0.1"
   },
   "devDependencies": {
     "jest": "^29.5.0"

package/templates/business-service/.gitlab-ci.yml

@@ -2,12 +2,13 @@
 # Written by @onlineapps/conn-orch-validator (row G-CI of
 # manifests/biz-service.manifest.json). The PLATFORM half of this pipeline: which
 # pipelines run at all, how a service is built, how its image is identified (R5),
-# how the digest reaches the deploy (R1/R2), that the installation document and
-# the migrations still agree, the uniform gate that runs before the SSH step
-# (confirmation biz-service-manifest 008) and the post-deploy gate that runs
-# after it (confirmation deploy-gate-targets 003). npx oa-sync-template .gitlab-ci.yml
-# --target . rewrites everything between these two markers and nothing outside
-# them.
+# how the digest reaches the deploy (R1/R2), the uniform gate that runs before
+# the SSH step (confirmation biz-service-manifest 008) and the post-deploy gate
+# that runs after it (confirmation deploy-gate-targets 003). The installation
+# contract is checked by that uniform gate, in the manifest rows G-SETUP,
+# D-DB-PACKAGE and D-DB-HEADERS, and no longer by a job of its own (d.470).
+# npx oa-sync-template .gitlab-ci.yml --target . rewrites everything between
+# these two markers and nothing outside them.
 #
 # Outside them is this repository's own: its test job - which database, which
 # ci:gate:* steps and which artefacts its integration needs is a fact about the
@@ -32,16 +33,6 @@ variables:
   IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
   IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest
 
-verify-installation-contract:
-  stage: test
-  image: alpine:latest
-  script:
-    - sh scripts/verify-installation-docs-sql-contract.sh
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-    - if: $CI_COMMIT_BRANCH == "main"
-    - if: $CI_COMMIT_BRANCH == "production"
-
 build:
   stage: build
   image: docker:24
@@ -357,9 +348,20 @@ deploy-production:
         # format the runbook writes in phase 1, so a schema already carried
         # forward is skipped rather than applied twice (confirmation 001:
         # "fáze 2 nesmí změnit sémantiku trackeru").
-        mkdir -p config/runtime
+        #
+        # Its EXISTENCE is the precondition, and the step never creates it.
+        # Confirmation 001 splits the work in two: phase 1 - schema, account and
+        # the first run of this same runner - is an operator's step in the
+        # runbook, and phase 2 is this job carrying that state forward. On a box
+        # phase 1 never touched there is no tracker, and a job that created one
+        # would apply the WHOLE series unattended on the first deploy, which is
+        # precisely the phase the owner kept manual. So a missing tracker stops
+        # the deploy and names the runbook, exactly as a missing schema does.
         TRACKER="config/runtime/applied-migrations-${DB_SCHEMA}.txt"
-        touch "$TRACKER"
+        if [ ! -f "$TRACKER" ]; then
+          echo "[deploy] Migrations tracker $DEPLOY_PATH/$TRACKER missing - phase 1 (the migrations of $DB_SCHEMA applied by hand with the same runner) has not run on this box. Expected: the flat tracker phase 1 leaves behind, carried forward by this deploy. Fix: run the business-schema migrations step of api/docs/setup/INSTALL.md for $DB_SCHEMA, then re-run this deploy. This step never creates the tracker: a deploy that did would apply the whole series unattended on a box nobody had provisioned." >&2
+          exit 1
+        fi
         apply_mariadb_migrations_over_tcp "$DB_MIGRATIONS_DIR" "$TRACKER" "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"
         # The runner logs each file it applies; what this line adds is the state
         # that outlives the deploy. The runner's own counter of files it passed
@@ -398,7 +400,6 @@ test:
   image: node:24-alpine
   variables:
     RABBITMQ_URL: "amqp://localhost:5672"
-    REGISTRY_URL: "http://localhost:33100"
     NODE_ENV: "test"
   script:
     - npm ci

package/templates/business-service/docs/80-setup/INSTALL.md

@@ -99,7 +99,7 @@ if it is missing, so onboarding a new service needs no manual step there.
 Between that `pull` and that `up` the deploy job applies this service's pending
 MariaDB migrations — the ordering is the safety: the new image is already on the
 box, the previous container is still serving, and a migration that fails stops
-the deploy before the switch. Two facts decide what happens:
+the deploy before the switch. Three facts decide what happens:
 
 - `config/service/integration-contract.json` → `database`. This scaffold declares
   no such block, so the step prints `NOT APPLICABLE (no database block)` and the
@@ -109,11 +109,18 @@ the deploy before the switch. Two facts decide what happens:
   `MARIADB_MIGRATION_PASSWORD`, the service's own account. The step creates
   neither the schema nor the account and refuses the deploy when that account
   cannot open the schema, naming the runbook instead.
-
-Who creates them, with which grants and which collation, is the runbook's step
-and is not repeated here: `api/docs/setup/INSTALL.md`, the business-schema step.
-The decision behind both halves — two phases, the service account as the
-isolation guard, one runner and one tracker across them — is owner confirmation
+- `config/runtime/applied-migrations-<schema>.txt` on the box — the tracker.
+  **It must already be there**, and this job never creates it. The file is what
+  phase 1 leaves behind: the operator who created the schema and the account also
+  ran the first pass of the same runner by hand, from the runbook. A deploy onto a
+  box phase 1 never touched therefore stops with `Migrations tracker … missing`
+  rather than applying the whole series unattended.
+
+Who creates the schema, the account and that first tracker — with which grants and
+which collation — is the runbook's step and is not repeated here:
+`api/docs/setup/INSTALL.md`, the business-schema step. The decision behind both
+halves — two phases, the service account as the isolation guard, one runner and
+one tracker across them — is owner confirmation
 `api/docs/governance/confirmations/db-migrations-first-deploy.md` 001.
 
 ## Status