@onlineapps/conn-orch-validator 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [8.1.0] — 2026-09-15
+
+### Changed — deploy job šablony aplikuje migrace DB mezi `pull` a `up` (d.421)
+
+Blok `oa-ci v1` v `templates/business-service/.gitlab-ci.yml` (řádek `G-CI`) má nový krok: po
+`compose pull` a **před** `compose up` pustí na biz boxu běžec `api/scripts/lib/mariadb-migrations.sh`
+z klonu api, který si krok uniformy vedle checkoutu stejně dělá — fáze 2 rozhodnutí vlastníka
+`api/docs/governance/confirmations/db-migrations-first-deploy.md` 001. Pořadí je ta pojistka:
+nový obraz je stažený, starý kontejner ještě obsluhuje, takže selhání migrace zastaví nasazení
+s běžící předchozí verzí. Běžec se **nese**, nekopíruje: proud, kterým ssh krmí `bash -s`, je řádek
+hesla, volby shellu, běžec z klonu api a teprve pak tělo skriptu — druhá implementace aplikátoru
+nevzniká nikde (`change-discipline.md` § One rail per concern).
+
+Co o schématu rozhoduje: `config/service/integration-contract.json`. Služba bez bloku `database`
+vypíše `NOT APPLICABLE (no database block)` a nasazuje se dál; služba s blokem dostane
+`database.schema` migrované z adresáře, který jmenuje `database.migrations`, s trackerem
+`config/runtime/applied-migrations-<schema>.txt` ve vlastním checkoutu na boxu (tentýž plochý formát
+jako fáze 1). Účet je účet služby (`MARIADB_MIGRATION_USER`/`_PASSWORD` z env souborů na boxu, nově
+deklarované v `config/env-templates/__SERVICE_NAME__.env`), nikdy root, a krok **nic nezakládá**:
+chybí-li klient `mysql`, klíč, env soubor nebo nemá-li účet na schéma právo, job zčervená s hláškou
+na runbook `api/docs/setup/INSTALL.md`.
+
+## [8.0.0] — 2026-09-14
+
 ### Added — zahazovací testovací schéma je export balíčku (d.407)
 
 `createThrowawaySchema` (`src/utils/throwawaySchema.js`, na indexu balíčku) staví schéma, které

package/package.json

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

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

@@ -198,6 +198,39 @@ deploy-production:
         exit 1
       fi
     - echo "Deploying $BIZ_IMAGE_DIGEST to $DEPLOY_HOST ($CI_ENVIRONMENT_URL)"
+    # The read-only api clone the uniform step already made beside this checkout.
+    # Derived from CI_PROJECT_DIR rather than spelled out a second time: the
+    # layout is declared once, in GIT_CLONE_PATH, so the two cannot drift apart.
+    # TWO steps read it: the migration runner streamed to the box below, and the
+    # post-deploy gate at the end of this job.
+    - API_CHECKOUT="$(dirname "$(dirname "$CI_PROJECT_DIR")")/api"
+    # WHICH SCHEMA, IF ANY (confirmation db-migrations-first-deploy 001, phase 2).
+    # Read from the one declaration there is - this service's own installation
+    # contract - and read HERE, on the runner: the contract is this repository's,
+    # jq is in this image, and the box is not asked to carry a JSON parser for two
+    # values. A service that declares no `database` block has no schema to
+    # migrate, and the step below says that out loud rather than passing over it
+    # in silence (automation-gates.md 5: a step that checked nothing must never
+    # look like one that checked).
+    - |
+      CONTRACT="$CI_PROJECT_DIR/config/service/integration-contract.json"
+      if [ ! -f "$CONTRACT" ]; then
+        echo "[deploy] FATAL: no installation contract at $CONTRACT - this deploy cannot tell whether the service has a schema to migrate, and guessing is not an option. Fix: commit config/service/integration-contract.json (the uniform manifest requires it of every biz repository)." >&2
+        exit 1
+      fi
+      BIZ_DB_SCHEMA="$(jq -r '.database.schema // empty' "$CONTRACT")"
+      BIZ_DB_MIGRATIONS="$(jq -r '.database.migrations // empty' "$CONTRACT")"
+      if [ -n "$BIZ_DB_SCHEMA" ] && [ -z "$BIZ_DB_MIGRATIONS" ]; then
+        echo "[deploy] FATAL: $CONTRACT declares database.schema ($BIZ_DB_SCHEMA) and no database.migrations - the deploy would not know which files to apply. Fix: declare the glob of the directory that holds them (api/docs/biz/70-contracts/database-contract.md)." >&2
+        exit 1
+      fi
+      if [ -n "$BIZ_DB_MIGRATIONS" ]; then
+        # The runner applies a DIRECTORY and does not descend into it; the
+        # contract declares the glob (migrations/*.sql, migrations/BASELINE/*.sql),
+        # so the directory is its dirname - the same reading the runbook gives it
+        # (api/docs/setup/INSTALL.md, applying a business schema).
+        BIZ_DB_MIGRATIONS="$(dirname "$BIZ_DB_MIGRATIONS")"
+      fi
     # DEPLOY_PATH / DEPLOY_HOST / DEPLOY_USER are CI variables: the box decides
     # where its checkout lives, and no path is baked into this file.
     #
@@ -208,18 +241,41 @@ deploy-production:
     # first and the script after it: the remote reads that one line, exports it,
     # and hands the rest of the stream to `bash -s` - ssh's stdin is a socket
     # there, so `read` consumes exactly the line and no more.
+    #
+    # The shell the remote runs is ASSEMBLED from three parts, in this order: the
+    # password line, the shell options, and then the platform's own MariaDB
+    # migration runner followed by the body below. The runner is carried rather
+    # than copied - it is api/scripts/lib/mariadb-migrations.sh out of the clone
+    # the uniform step made, so the box applies the same shell the runbook applies
+    # by hand in phase 1, and no second implementation of it exists anywhere
+    # (change-discipline.md - One rail per concern). The options are set once, for
+    # the whole assembled stream, which is why they are no longer the first line
+    # of the body.
     - |
       {
         printf '%s\n' "$CI_REGISTRY_PASSWORD"
+        printf '%s\n' "set -euo pipefail"
+        cat "$API_CHECKOUT/scripts/lib/mariadb-migrations.sh"
         cat
-      } <<'REMOTE' | ssh $DEPLOY_USER@$DEPLOY_HOST "IFS= read -r REGISTRY_PASSWORD; export REGISTRY_PASSWORD; bash -s -- '$DEPLOY_PATH' '$CI_REGISTRY' '$CI_REGISTRY_USER' '$CI_PROJECT_PATH_SLUG' '$BIZ_IMAGE_DIGEST' '$CI_PROJECT_PATH'"
-      set -euo pipefail
+      } <<'REMOTE' | ssh $DEPLOY_USER@$DEPLOY_HOST "IFS= read -r REGISTRY_PASSWORD; export REGISTRY_PASSWORD; bash -s -- '$DEPLOY_PATH' '$CI_REGISTRY' '$CI_REGISTRY_USER' '$CI_PROJECT_PATH_SLUG' '$BIZ_IMAGE_DIGEST' '$CI_PROJECT_PATH' '$BIZ_DB_SCHEMA' '$BIZ_DB_MIGRATIONS'"
       DEPLOY_PATH="$1"
       REGISTRY="$2"
       REGISTRY_USER="$3"
       PROJECT_SLUG="$4"
       export BIZ_IMAGE_DIGEST="$5"
       PROJECT_PATH="$6"
+      # Empty when the installation contract declares no `database` block - the
+      # only thing that turns the migration step below on or off.
+      DB_SCHEMA="$7"
+      DB_MIGRATIONS_DIR="$8"
+      # This service's own env file on the box, the per-machine half of the two
+      # the compose file names (../shared.env is the host's). It carries the
+      # migration account - the SAME account the service connects as.
+      SERVICE_ENV="config/env-active/__SERVICE_NAME__.env"
+      # The host-level env file of the biz box, one per box and referenced rather
+      # than copied (server-topology 004) - the same path docker-compose.production.yml
+      # names.
+      HOST_ENV="../shared.env"
       # REGISTRY_PASSWORD arrives in the environment, from the first line of this
       # script's own stdin. Empty means the runner had no CI_REGISTRY_PASSWORD:
       # the pull would fail later with an authentication error that names nothing.
@@ -247,6 +303,72 @@ deploy-production:
       echo "$REGISTRY_PASSWORD" | docker --config "$DOCKER_CONFIG_DIR" login -u "$REGISTRY_USER" --password-stdin "$REGISTRY"
       echo "[deploy] pulling $BIZ_IMAGE_DIGEST"
       docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml pull
+
+      # ─── Migrations: after the pull, before the switch ───────────────
+      # Owner decision api/docs/governance/confirmations/db-migrations-first-deploy.md
+      # 001, phase 2. The ordering IS the safety: at this point the new image is
+      # on the box and the OLD container is still serving, so a migration that
+      # fails stops the deploy with the previous version running and the new one
+      # never started. Applying after the switch would mean the new code meets a
+      # schema it does not have; applying before the pull would mean a schema
+      # change for an image that might not even be pullable.
+      #
+      # The account is the SERVICE's, never root: its grants cover its own schema
+      # and nothing else, so a migration that reaches sideways into a neighbouring
+      # database is refused by the server rather than politely applied
+      # (db-accounts-per-service 001). This step CREATES NOTHING - schema and
+      # account are an operator's step in the runbook, phase 1, and a deploy that
+      # provisioned what it found missing would both grant itself those privileges
+      # and hide a wrongly provisioned box.
+      if [ -z "$DB_SCHEMA" ]; then
+        echo "[deploy] migrations NOT APPLICABLE (no database block) - config/service/integration-contract.json declares no database, so this service has no schema to migrate."
+      else
+        # The two env files the compose names, in the order it names them: the
+        # host-level one first, this service's own second, so the same value wins
+        # here that wins inside the container. Reading only one of them would
+        # make this step disagree with the service it migrates for, depending on
+        # which file the box happens to carry DB_HOST in.
+        for env_file in "$HOST_ENV" "$SERVICE_ENV"; do
+          if [ ! -f "$env_file" ]; then
+            echo "[deploy] Missing env file - $env_file does not exist on this box, and docker-compose.production.yml names it: between the two of them they carry the endpoint and the migration account of $DB_SCHEMA. Fix: place it on the box (both are per-machine and never committed), then re-run this deploy." >&2
+            exit 1
+          fi
+          set -a
+          . "$env_file"
+          set +a
+        done
+        missing=""
+        [ -n "${MARIADB_MIGRATION_USER:-}" ] || missing="$missing MARIADB_MIGRATION_USER"
+        [ -n "${MARIADB_MIGRATION_PASSWORD:-}" ] || missing="$missing MARIADB_MIGRATION_PASSWORD"
+        [ -n "${DB_HOST:-}" ] || missing="$missing DB_HOST"
+        [ -n "${DB_PORT:-}" ] || missing="$missing DB_PORT"
+        if [ -n "$missing" ]; then
+          echo "[deploy] Missing environment variable -$missing in $DEPLOY_PATH/$SERVICE_ENV. Expected: the migration account of $DB_SCHEMA (the same account as DB_USER, granted on that schema only) and the endpoint it is reached at. Fix: add the keys to that file on this box; config/env-templates/ declares each of them with the reason it exists." >&2
+          exit 1
+        fi
+        # The precondition confirmation 001 demands before any migration: the
+        # account opens the schema, or this deploy stops and names the runbook.
+        if ! mariadb_migrations_can_open_over_tcp "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"; then
+          echo "[deploy] Schema or account missing - '$MARIADB_MIGRATION_USER' cannot open '$DB_SCHEMA' at $DB_HOST:$DB_PORT. Expected: the schema and the account, with grants on ${DB_SCHEMA}.* and nothing else, provisioned once by an operator. Fix: run the business-schema step of api/docs/setup/INSTALL.md on the infra box, then re-run this deploy. This step never creates either: provisioning is a decision, not a deploy side effect." >&2
+          exit 1
+        fi
+        # The tracker is the caller's state and it lives in the checkout on this
+        # box, under the gitignored config/runtime/ - same file name and same flat
+        # 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
+        TRACKER="config/runtime/applied-migrations-${DB_SCHEMA}.txt"
+        touch "$TRACKER"
+        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
+        # over is deliberately not echoed: no word that reads as a bypass belongs
+        # anywhere in a deploy job, and the gate that keeps this job free of one
+        # judges by the word, not by the intent.
+        echo "[deploy] migrations $DB_SCHEMA: $MARIADB_MIGRATIONS_APPLIED applied now, $(wc -l < "$TRACKER" | tr -d " ") recorded in $DEPLOY_PATH/$TRACKER"
+      fi
+
       docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml up -d
       REMOTE
     # The deploy is not finished until the platform's own post-deploy gate says
@@ -257,11 +379,8 @@ deploy-production:
     # runs in remote mode — same script, same contract, same verdicts as a local
     # run, only reading over ssh.
     - |
-      # The gate runs out of the read-only api clone the uniform step already
-      # made beside this checkout. Derived from CI_PROJECT_DIR rather than
-      # spelled out a second time: the layout is declared once, in
-      # GIT_CLONE_PATH, so the two cannot drift apart.
-      API_CHECKOUT="$(dirname "$(dirname "$CI_PROJECT_DIR")")/api"
+      # The gate runs out of the same read-only api clone the migration runner
+      # was streamed from; API_CHECKOUT is derived once, above.
       bash "$API_CHECKOUT/scripts/run-post-deploy-gate.sh" \
         --target "$DEPLOY_GATE_TARGETS" \
         --biz-host "$DEPLOY_USER@$DEPLOY_HOST" \

package/templates/business-service/config/env-templates/__SERVICE_NAME__.env

@@ -2,3 +2,21 @@
 # Copy to config/env-active/__SERVICE_NAME__.env and adjust values.
 
 SERVICE_NAME=__SERVICE_NAME__
+
+# Schema migrations at deploy time. The deploy job (block `oa-ci v1` of
+# .gitlab-ci.yml) runs api/scripts/lib/mariadb-migrations.sh between `compose
+# pull` and `compose up`, and that runner REQUIRES both names - fail-fast, no
+# default value (owner decision
+# api/docs/governance/confirmations/db-migrations-first-deploy.md 001, phase 2).
+# The account is the SAME one DB_USER names: its grants cover this service's
+# schema and nothing else, so a migration that reached into a neighbouring
+# database is refused by the server instead of quietly applied
+# (db-accounts-per-service 001). Pattern: api/config/env-templates/auth.env.
+#
+# Commented out because this scaffold has no database: its
+# config/service/integration-contract.json declares no `database` block, the
+# deploy step prints NOT APPLICABLE and reads neither name. A service that
+# declares that block uncomments both here and fills the values in
+# config/env-active/ only - per machine, never in git.
+# MARIADB_MIGRATION_USER=
+# MARIADB_MIGRATION_PASSWORD=

package/templates/business-service/config/env-templates/shared.env

@@ -40,7 +40,7 @@ MINIO_ACCESS_KEY=CHANGE_ME
 # The secret of that same object-store account; shares the compose-interpolation note of MINIO_ACCESS_KEY.
 MINIO_SECRET_KEY=CHANGE_ME
 
-# How often (ms) a business service publishes its MQ heartbeat, and the ONE source of truth for how fresh that signal has to be: every staleness threshold is a multiple of this cadence (BIZ_HEARTBEAT_STALE_FACTOR), never a second duration set by hand - owner decision docs/governance/confirmations/biz-health-freshness.md 001, which supersedes the absolute INFRASTRUCTURE_HEALTH_BUSINESS_STALE_AFTER of batch 111a. It is shared because the publisher and the judge are different processes: the registry derives its monitor and janitor thresholds from it today, and @onlineapps/service-wrapper is to read it in place of the wrapper.registry.heartbeatInterval runtime default, so a cadence change cannot reach one side only.
+# How often (ms) a business service publishes its MQ heartbeat, and the ONE source of truth for how fresh that signal has to be: every staleness threshold is a multiple of this cadence (BIZ_HEARTBEAT_STALE_FACTOR), never a second duration set by hand - owner decision docs/governance/confirmations/biz-health-freshness.md 001, which supersedes the absolute INFRASTRUCTURE_HEALTH_BUSINESS_STALE_AFTER of batch 111a. It is shared because the publisher and the judge are different processes: the registry derives its monitor and janitor thresholds from it today, and @onlineapps/service-wrapper reads it as the only cadence there is (the wrapper.registry.heartbeatInterval config key is retired and refused by name), so a cadence change cannot reach one side only.
 BIZ_HEARTBEAT_INTERVAL_MS=30000
 
 # How many heartbeat cadences a business service may stay silent before it is judged stale; the only knob on top of BIZ_HEARTBEAT_INTERVAL_MS, and the reason no threshold is written as a duration anywhere (owner decision docs/governance/confirmations/biz-health-freshness.md 001: the factor is config, not doctrine - changing it is an ordinary config change). May be fractional; the derived threshold is whole milliseconds.

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

@@ -94,6 +94,28 @@ CI publishes that digest from the build stage and the deploy job refuses to run
 without it (requirement R1). A first deploy also clones the checkout on the box
 if it is missing, so onboarding a new service needs no manual step there.
 
+### Migrations at deploy time
+
+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:
+
+- `config/service/integration-contract.json` → `database`. This scaffold declares
+  no such block, so the step prints `NOT APPLICABLE (no database block)` and the
+  deploy carries on. A service that declares one has its `database.schema`
+  migrated from the directory `database.migrations` names.
+- `config/env-active/__SERVICE_NAME__.env` → `MARIADB_MIGRATION_USER` and
+  `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
+`api/docs/governance/confirmations/db-migrations-first-deploy.md` 001.
+
 ## Status
 
 Current. One of the three files the installation contract requires by name —