@onlineapps/conn-orch-validator 11.0.0 → 12.0.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [12.0.0] — 2026-09-17
+
+### Fixed — BREAKING: R2 tvrdí pravidlo sekvence nasazení, ne včerejší text (d.614, W614)
+
+`src/utils/deployContract.js`: R2 vyžadovalo doslovné `git reset --hard origin/production`, což je OPAK toho, co blok
+`oa-ci v1` nese od d.589b (`e138d1f9`) — `git merge-base --is-ancestor "$COMMIT_SHA" origin/production` a pak
+`git reset --hard "$COMMIT_SHA"`. Brána `ci:gate:contract` je první krok `before_script` jobu `test`, takže služba se
+syncnutým blokem 11.0.0 padala na R2 ještě před prvním testem (změřeno 17. 9. u pdfgen a hello-service; ostatních šest
+neslo starý tvar, tedy jednu synchronizaci od téhož). R2 nově čte PRAVIDLO: nasazení nikdy nemerguje (`git pull` i
+`git merge`, `merge-base` není merge), resetuje na commit, který pipeline měřila, a guard `merge-base --is-ancestor …
+origin/production` musí stát PŘED tím resetem a jmenovat týž commit. Odolné vůči uvozovkám, mezerám a `; then`,
+nikoli benevolentní: reset bez guardu, guard až za resetem, guard na jiný commit nebo jinou větev i samotný včerejší
+`git reset --hard origin/production` jsou FAIL. Žádná přechodná tolerance (architecture-principles §11); hláška jmenuje
+dnešní tvar a jediný příkaz, který ho zapíše — `npx oa-sync-template .gitlab-ci.yml --target .`. Všech osm služeb má
+blok `oa-ci v1` rozejitý už dnes (`oa-sync-template .gitlab-ci.yml --check` = DRIFT u 8/8), takže R2 nepřidává povinnost,
+kterou uniforma nenese.
+
+### Added — sada „vlastní šablona projde vlastní bránou“ (d.614, W614)
+
+`tests/unit/deployContractTemplate.test.js` renderuje `templates/business-service` týmiž helpery, kterými ji renderuje
+`oa-sync-template --new` (`renderTree` + `deriveParams` + přejmenování env šablony), a pouští nad výsledkem
+`verifyDeployContract`: 0 porušení. Chyběl právě tenhle spoj — každý případ R2 si dosud psal `.gitlab-ci.yml` ručně, takže
+pravidlo i blok šlo měnit nezávisle a obě strany zůstaly zelené. Sada nese i tři případy, které dokazují, že umí zčervenat
+(reset bez guardu, včerejší tvar, kontrolní případ mimo sekvenci). Ruční vstupy sad `deployContract`, `deployContractR7Declared`,
+`bizCiGateCli.{envContract,installContract}` a helperu `conformantBizRepo` jsou srovnané na dnešní tvar.
+
+### Changed — BREAKING: blok `G-CI` deklaruje DVA refy api místo jednoho (d.612, W612)
+
+`templates/business-service/.gitlab-ci.yml`: `API_UNIFORM_REF_CONTINUOUS: main` čte průběžný job `validate-uniform`,
+`API_UNIFORM_REF_DEPLOY: production` čte `deploy-production` — jeho krok uniformy i běžec migrací a seedů, kterého nese na
+box. `API_UNIFORM_REF` zaniká bez aliasu a bez přechodného čtení. Průběžná brána (konfirmace `biz-service-manifest` 010)
+měřila api `production`, která se pohne až na konci produkční cesty (push té větve je nasazení infra), takže byla červená
+u všech osmi služeb z důvodu mimo kteroukoli z nich. Rozhodnutí vlastníka: `biz-service-manifest` 012. Služba srovná blok
+jedním během `npx oa-sync-template .gitlab-ci.yml --target .`; do té doby její `validate-uniform` měří dál `production`.
+`scripts/verify-deploy-uniform.sh` bere ref argumentem jako dosud; jeho hláška o prázdném refu jmenuje obě proměnné.
+
+### Fixed — `ManifestDiscovery` „Referenced file not found“ radí to, co jde udělat (d.611, W612)
+
+Soubor chybějící v api checkoutu, KTERÝ běh dosáhl, už neposílá CI job za `--workspace` (ten si job dosazuje sám): hláška
+jmenuje checkout a `Fix:` říká aktualizovat ho lokálně, nebo posunout ref api, proti kterému job měří. Workspace bez api
+checkoutu dostává dosavadní radu. V obou větvích zůstává tvrdý pád — chybějící SSOT v dosažitelném workspace je nález, ne
+NOT RUN; říká to i `why` řádku `G-SHARED-ENV`.
+
+### Fixed — workspace id ≤ 0 se odmítá na obou kolejích (d.606 + d.606b, W606)
+
+`assertWorkspaceId` odmítá `0` i záporná čísla a prochází jím hodnota deklarovaná receptem (`defaults.workspace_id`,
+per-step) i hodnota z prostředí (`TESTING_WORKSPACE_ID` v `getTestNamespace()`). Konfirmace `tier1-runner-workspace` 002
+říká „kladné celé číslo“, kód kontroloval jen `Number.isInteger`: `TESTING_WORKSPACE_ID=0` vracelo `workspace_id: 0` a recept
+s `workspace_id: 0` prošel Tier-1 cestou až k odeslání kroku. Odmítnutí jmenuje klíč, místo, kde se nastavuje, a normu
+`api/docs/standards/tenant-allocation.md`. Tenantí kolej beze změny. Dopad na dnešní recepty a env služeb: 0 výskytů ≤ 0.
+
+
 ## [11.0.0] — 2026-09-17
 
 ### Changed — deploy job aplikuje seedy třídy PRODUCTION_LIKE (d.589, W589)

package/manifests/biz-service.manifest.json

@@ -446,7 +446,7 @@
         "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",
+        "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 .",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a718"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"

package/src/manifest/discovery.js

@@ -21,7 +21,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { resolveWorkspacePath } = require('./workspaceRoot');
+const { resolveWorkspacePath, apiCheckoutOf } = require('./workspaceRoot');
 
 /** Never walked: neither is part of any repository's declared shape. */
 const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
@@ -211,11 +211,50 @@ function readReferencedFile({ from, workspaceRoot }) {
   try {
     return fs.readFileSync(file, 'utf8');
   } catch (cause) {
-    throw new Error(`[ManifestDiscovery] Referenced file not found - ${from.path} under ${workspaceRoot}. `
-      + 'Fix: run with --workspace pointing at the directory that holds api/ and api_biz/.', { cause });
+    throw new Error(describeMissingReference({ from, workspaceRoot, file }), { cause });
   }
 }
 
+/**
+ * Why a `from:` file could not be read, said as the two different things it can
+ * be — because the reader's next move is a different one in each case.
+ *
+ * The run was pointed at a workspace that carries no api checkout: the layout is
+ * the problem, and `--workspace` is the answer it has always been.
+ *
+ * The run REACHED the checkout and the file is not in it: the layout is right
+ * and the advice to pass `--workspace` is one nobody can carry out — a CI job
+ * passes that flag itself. Measured on BIZ-invoicing 2026-09-17: the job reached
+ * `api/`, and the clone made at the api ref that job measures against did not
+ * carry `api/config/shared-env.json`, because that ref predates the file. What
+ * moves is the checkout (locally) or the ref (in CI), so the message names both,
+ * and it names the ref by variable — the two of confirmation
+ * `biz-service-manifest` 012.
+ *
+ * It stays a hard failure in both cases: a missing SSOT in a workspace this run
+ * CAN read is a finding, never a NOT RUN (`automation-gates.md` §5).
+ *
+ * @param {{ from: {path: string}, workspaceRoot: string, file: string }} params
+ * @returns {string}
+ */
+function describeMissingReference({ from, workspaceRoot, file }) {
+  const apiRoot = apiCheckoutOf(workspaceRoot);
+  const insideApiCheckout = apiRoot !== null
+    && path.resolve(file).startsWith(apiRoot + path.sep);
+
+  if (!insideApiCheckout) {
+    return `[ManifestDiscovery] Referenced file not found - ${from.path} under ${workspaceRoot}. `
+      + 'Fix: run with --workspace pointing at the directory that holds api/ and api_biz/.';
+  }
+
+  return `[ManifestDiscovery] Referenced file not found - ${from.path} is missing from the api checkout `
+    + `${apiRoot}, which this run reached. The workspace is there and so is the checkout, so this is `
+    + 'not a --workspace problem: the checkout does not carry the file at the state it stands on. '
+    + `Fix: locally, update that checkout (git -C ${apiRoot} pull); in CI, move the api ref this job `
+    + 'measures against to a commit that carries the file - API_UNIFORM_REF_CONTINUOUS for the '
+    + 'validate-uniform job, API_UNIFORM_REF_DEPLOY for deploy-production.';
+}
+
 /**
  * The whole referenced file as one value: `{ path, text: true }`.
  *

package/src/utils/deployContract.js

@@ -8,7 +8,8 @@
  * R8 permits and their reasons: api/docs/standards/tenant-allocation.md § Enforcement
  *
  *   R1  the production compose pins its image immutably
- *   R2  the deploy resets to origin/production rather than merging
+ *   R2  the deploy never merges: it resets to the commit the pipeline measured,
+ *       after verifying that commit is an ancestor of origin/production
  *   R3  CI Node major == Dockerfile Node major == engines.node major
  *   R4  no published ports — the only public entrypoint is doorman
  *   R5  images tagged with the full commit SHA, never the short one
@@ -138,15 +139,124 @@ function checkPublishedPorts(compose, add) {
   }
 }
 
+// ── R2 — the deploy sequence ────────────────────────────────────────────────
+//
+// The rule, stated once and in full: a deploy on the box NEVER merges; it forces
+// the checkout to the commit THIS PIPELINE MEASURED, and before it does, it
+// verifies that commit is an ancestor of origin/production.
+//
+// Both halves are load-bearing, and each answers a different way a box ends up
+// running something nobody measured:
+//
+//   the measured commit — the runner read config/service/integration-contract.json
+//   at $CI_COMMIT_SHA and derived the migration directory and the seed list from
+//   it THERE. Resetting to origin/production instead lands the box on whatever
+//   the branch points at by the time the ssh step opens, so a push that arrives
+//   while the job runs leaves it applying a declaration no run ever measured.
+//
+//   the ancestor check — a commit that is not on the branch this box follows is
+//   a pipeline for a different history, and resetting to it puts the box on code
+//   production never took. Fail-fast, before anything is touched.
+//
+// Until 2026-09-17 this function demanded the literal `git reset --hard
+// origin/production`, which is the FIRST half's opposite. The packaged template
+// had carried the two-step form since d.589b, so a repository that synced the
+// block failed the gate byte-for-byte conformant — measured in pdfgen and
+// hello-service, both of which run `ci:gate:contract` as the first before_script
+// step of `test` and would therefore have failed before their first test. A rule
+// that states yesterday's TEXT rather than the requirement is exactly what
+// `.claude/rules/doc-code-binding.md` §1 calls a descriptive fact written by
+// hand; `tests/unit/deployContractTemplate.test.js` is what now re-derives it,
+// by running this gate over the template this package ships.
+//
+// There is no transition tolerance for the old form, and there must not be
+// (`architecture-principles.md` §11): the six repositories still carrying it get
+// a message naming today's form and the one command that writes it.
+
+/** The branch a production box follows — the only ref an ancestor check may name. */
+const PRODUCTION_BRANCH = 'origin/production';
+
+/** `git reset --hard <ref>`, tolerant of the spacing a shell allows. */
+const RESET_HARD = /(?:^|[^\w-])git\s+reset\s+--hard\s+(\S+)/g;
+
+/** `git merge-base --is-ancestor <commit> <ref>` — the guard, same tolerance. */
+const ANCESTOR_CHECK = /(?:^|[^\w-])git\s+merge-base\s+--is-ancestor\s+(\S+)\s+(\S+)/g;
+
+/** `git merge …`. `git merge-base` is a different command, so it must not match. */
+const GIT_MERGE = /(?:^|[^\w-])git\s+merge(?![-\w])/;
+
+/** `git pull …` */
+const GIT_PULL = /(?:^|[^\w-])git\s+pull(?:[^\w-]|$)/m;
+
+/** The block this package ships, named in every fix so nobody has to retype it. */
+const DEPLOY_SEQUENCE_FIX =
+  '       Fix: npx oa-sync-template .gitlab-ci.yml --target . — the packaged block `oa-ci v1`\n'
+  + '       carries the sequence: git fetch origin production, then\n'
+  + '       `if ! git merge-base --is-ancestor "$COMMIT_SHA" origin/production; then exit 1; fi`,\n'
+  + '       then `git reset --hard "$COMMIT_SHA"`.';
+
+/**
+ * One shell word as this rule reads it: the separators a shell puts after an
+ * argument (`; then`, `&& …`) dropped, then the quotes.
+ *
+ * Tolerant, deliberately not lenient: what it normalises away is punctuation
+ * that cannot change which commit the command names.
+ */
+function shellWord(raw) {
+  return unquote(raw.replace(/[;&|)]+$/, ''));
+}
+
 function checkDeploySequence(ci, add) {
-  if (/(^|[^\w-])git\s+pull([^\w-]|$)/m.test(ci)) {
+  if (GIT_PULL.test(ci)) {
     add('R2', "'git pull' in the deploy path.\n"
       + '       A local modification on the server turns the merge into a conflict and aborts the deploy halfway.\n'
-      + '       Fix: git fetch origin production && git reset --hard origin/production');
+      + DEPLOY_SEQUENCE_FIX);
   }
-  if (!/git\s+reset\s+--hard\s+origin\/production/.test(ci)) {
-    add('R2', "No 'git reset --hard origin/production' found in .gitlab-ci.yml.\n"
-      + '       Fix: the deploy must force the working tree to the pushed commit, matching the infra contract.');
+  if (GIT_MERGE.test(ci)) {
+    add('R2', "'git merge' in the deploy path.\n"
+      + '       A deploy that merges builds a commit that exists on no branch, so what the box runs\n'
+      + '       is no longer any commit a pipeline measured.\n'
+      + DEPLOY_SEQUENCE_FIX);
+  }
+
+  const resets = [...ci.matchAll(RESET_HARD)]
+    .map((match) => ({ at: match.index, target: shellWord(match[1]) }));
+
+  if (resets.length === 0) {
+    add('R2', "No 'git reset --hard' found in .gitlab-ci.yml.\n"
+      + '       The deploy has to force the working tree to the commit this pipeline measured;\n'
+      + '       nothing here does.\n'
+      + DEPLOY_SEQUENCE_FIX);
+    return;
+  }
+
+  // Ordering is read over the whole file rather than per job: which YAML key a
+  // line sits under is the service's own half of the pipeline, and a gate that
+  // parsed jobs would be judging that half too. What it does measure is the
+  // thing that can go wrong — a guard that names another commit, another branch,
+  // or runs after the reset it is supposed to protect.
+  const guards = [...ci.matchAll(ANCESTOR_CHECK)]
+    .map((match) => ({ at: match.index, commit: shellWord(match[1]), branch: shellWord(match[2]) }))
+    .filter((guard) => guard.branch === PRODUCTION_BRANCH);
+
+  for (const reset of resets) {
+    if (reset.target === PRODUCTION_BRANCH) {
+      add('R2', `The deploy resets to ${PRODUCTION_BRANCH}, not to the commit this pipeline measured.\n`
+        + '       origin/production is whatever the branch points at by the time the ssh step opens:\n'
+        + '       a push landing while this job runs leaves the box applying a declaration no run\n'
+        + '       ever measured, because the migration set was derived at the pipeline commit.\n'
+        + DEPLOY_SEQUENCE_FIX);
+      continue;
+    }
+    if (!guards.some((guard) => guard.at < reset.at && guard.commit === reset.target)) {
+      add('R2', `The deploy resets to ${reset.target}, which is not verified to be an ancestor of `
+        + `${PRODUCTION_BRANCH} first.\n`
+        + '       A commit that is not on the branch this box follows belongs to a different history,\n'
+        + '       and resetting to it puts the box on code production never took.\n'
+        + `       Expected: git merge-base --is-ancestor ${reset.target} ${PRODUCTION_BRANCH}, on a line\n`
+        + '       BEFORE the reset, naming that same commit.\n'
+        + DEPLOY_SEQUENCE_FIX);
+    }
   }
 }
 

package/src/utils/testNamespace.js

@@ -202,6 +202,16 @@ function assertAllowedTenant(tenantId, options) {
  * fallback there would hide exactly the misconfiguration the boundary exists to
  * surface (architecture-principles.md §3).
  *
+ * What it DOES hold is the shape of a workspace id: a POSITIVE integer. The
+ * recorded decision names it (api/docs/governance/confirmations/tier1-runner-workspace.md,
+ * entry 002) and `.claude/rules/workspace-architecture.md` says `workspace_id` 0
+ * is not a value; the guard checked `Number.isInteger` only, so `0` and `-5` came
+ * back normalized and a cookbook could send the boot probe into a workspace that
+ * cannot exist. The check lives here rather than in `normalizeNamespaceId()`
+ * because the tenant rail already refuses both — by the class allowlist, for a
+ * different reason and with a different fix — and one message per boundary is
+ * what keeps the refusal actionable.
+ *
  * There is deliberately NO class allowlist here, and that is not an omission:
  *
  *   - `api/docs/standards/tenant-allocation.md` allocates environment classes to
@@ -222,7 +232,7 @@ function assertAllowedTenant(tenantId, options) {
  *        `purpose` is the name the caller knows the id by (here, the cookbook key
  *        that carries it), `setBy` where that name is given a value.
  * @returns {number} the normalized id.
- * @throws {Error} when the id is absent or not an integer.
+ * @throws {Error} when the id is absent, not an integer, or not positive.
  */
 function assertWorkspaceId(workspaceId, options) {
   if (options === null || typeof options !== 'object') {
@@ -232,7 +242,14 @@ function assertWorkspaceId(workspaceId, options) {
   requireOriginText(purpose, 'purpose');
   requireOriginText(setBy, 'setBy');
 
-  return normalizeNamespaceId(workspaceId, { purpose, setBy });
+  const value = normalizeNamespaceId(workspaceId, { purpose, setBy });
+  if (value <= 0) {
+    throw new Error(`[TestNamespace] Invalid ${purpose}=${value} - Expected a positive integer `
+      + 'workspace id (1 or greater); 0 identifies no workspace. '
+      + `Fix: set ${purpose} to the workspace the run owns - ${setBy} - `
+      + 'see api/docs/standards/tenant-allocation.md § The allocation.');
+  }
+  return value;
 }
 
 /**
@@ -275,9 +292,19 @@ function getTestNamespace() {
     setBy: ENV_SET_BY
   });
 
+  // The workspace takes the same shape check a cookbook's declared value takes,
+  // under the same function and the same sentence. It did not, and that made the
+  // boundary half a boundary: the positivity rule held for a value a cookbook
+  // declares and not for the variable every integration test and every boot
+  // probe actually runs under (measured: TESTING_WORKSPACE_ID=0 returned
+  // workspace_id 0). The tenant above shows the shape — the env is one caller of
+  // a boundary, never its owner.
   return {
     tenant_id: tenantId,
-    workspace_id: readNamespaceId('TESTING_WORKSPACE_ID')
+    workspace_id: assertWorkspaceId(readNamespaceId('TESTING_WORKSPACE_ID'), {
+      purpose: 'TESTING_WORKSPACE_ID',
+      setBy: ENV_SET_BY
+    })
   };
 }
 

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

@@ -68,12 +68,24 @@ variables:
     # ABOVE api_biz, so the sibling api/ still lands beside this checkout, which
     # is the layout verify-deploy-uniform.sh checks.
     GIT_CLONE_PATH: $CI_BUILDS_DIR/oa-uniform/$CI_CONCURRENT_ID/api_biz/__SERVICE_NAME__
-    # Where the platform SSOT is read from, and which state of it a run is
-    # measured against. Read access is granted by the api project's CI job-token
-    # allowlist - the owner's step, outside any repository (confirmation
-    # biz-service-manifest 008 point 2).
+    # WHERE the platform SSOT is read from. Read access is granted by the api
+    # project's CI job-token allowlist - the owner's step, outside any
+    # repository (confirmation biz-service-manifest 008 point 2).
     API_PROJECT_PATH: onlineapps/oadrive/infra-mono
-    API_UNIFORM_REF: production
+    # WHICH STATE of that SSOT a run is measured against - two facts, two names
+    # (confirmation biz-service-manifest 012; 010 for the continuous run, 008
+    # point 3 for the binding one).
+    #
+    # The continuous gate judges the commit in front of it, so it measures
+    # against the branch the platform develops on - the same one the libraries
+    # SSOT is read from. api production moves only at the END of a production
+    # path, and pushing it deploys infra, so a continuous gate pointed there
+    # measures a months-old ref and goes red for a reason outside this
+    # repository (automation-gates.md §5).
+    API_UNIFORM_REF_CONTINUOUS: main
+    # The deploy confirms against what is being deployed, and the migration
+    # runner this job carries onto the box comes from that same clone.
+    API_UNIFORM_REF_DEPLOY: production
 
 # The uniform of THIS commit, on every pipeline - confirmation
 # biz-service-manifest 010. Entry 008 places the BINDING run before the SSH step
@@ -102,7 +114,7 @@ validate-uniform:
     # second place to keep in step (change-discipline.md - One rail per
     # concern). It comes from the package this repository pins, beside the
     # engine it runs.
-    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
+    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF_CONTINUOUS"
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main"
@@ -247,7 +259,7 @@ deploy-production:
     # not look everywhere, and nothing reaches the box. There is no flag and no
     # variable that turns this off (automation-gates.md §1 requirement 5).
     - npm ci
-    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
+    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF_DEPLOY"
     # R1: refuse to deploy without the immutable target the build stage published.
     - |
       if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
@@ -474,13 +486,13 @@ deploy-production:
           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 runner is carried from the api clone at API_UNIFORM_REF, so a ref
+        # The runner is carried from the api clone at API_UNIFORM_REF_DEPLOY, so a ref
         # older than the seed entry point would reach `command not found` here -
         # after the migrations and before the switch, in a production deploy and
         # nowhere else. Checked before the first statement instead
         # (automation-gates.md §1 requirement 4).
         if [ -n "$DB_SEEDS" ] && ! declare -F apply_mariadb_seeds_over_tcp > /dev/null 2>&1; then
-          echo "[deploy] FATAL: the migration runner carried from the api clone has no apply_mariadb_seeds_over_tcp, and $DB_SCHEMA declares PRODUCTION_LIKE seeds this deploy has to apply. Expected: that entry point in api/scripts/lib/mariadb-migrations.sh. Fix: move API_UNIFORM_REF to an api commit that carries it, and re-run this deploy." >&2
+          echo "[deploy] FATAL: the migration runner carried from the api clone has no apply_mariadb_seeds_over_tcp, and $DB_SCHEMA declares PRODUCTION_LIKE seeds this deploy has to apply. Expected: that entry point in api/scripts/lib/mariadb-migrations.sh. Fix: move API_UNIFORM_REF_DEPLOY to an api commit that carries it, and re-run this deploy." >&2
           exit 1
         fi
         # The precondition confirmation 001 demands before any migration: the

package/templates/business-service/scripts/verify-deploy-uniform.sh

@@ -32,7 +32,8 @@
 # WHY THREE ARGUMENTS AND NOTHING FROM THE ENVIRONMENT. The script knows what to
 # measure, never where the pieces come from (`architecture-principles.md` §1):
 # the job passes the checkout GitLab made, the api repository URL carrying its
-# job token, and the api ref that production follows. Nothing here reads
+# job token, and the api ref THAT job measures against (the continuous job and
+# the deploy job name different ones - confirmation biz-service-manifest 012). Nothing here reads
 # `process.env`, so the same invocation is reproducible outside CI.
 #
 # THE LAYOUT IT NEEDS, AND WHY THE JOB HAS TO ASK FOR IT. The engine answers the
@@ -69,7 +70,7 @@ API_URL="$2"
 API_REF="$3"
 
 [ -n "$API_URL" ] || die "The api repository URL is empty - the uniform reads the platform SSOT from that checkout, and this script does not guess where it lives. Expected: the URL the job builds from CI_JOB_TOKEN. Fix: pass it as the second argument." 2
-[ -n "$API_REF" ] || die "The api ref is empty - which state of the platform this deploy is measured against is a decision, not a default. Expected: the branch production follows. Fix: pass it as the third argument." 2
+[ -n "$API_REF" ] || die "The api ref is empty - which state of the platform this deploy is measured against is a decision, not a default. Expected: the ref the calling job declares (API_UNIFORM_REF_CONTINUOUS for validate-uniform, API_UNIFORM_REF_DEPLOY for deploy-production). Fix: pass it as the third argument." 2
 [ -d "$SERVICE_ROOT" ] || die "Service root not found - '$SERVICE_ROOT' is not an existing directory. Expected: the checkout being deployed. Fix: pass \$CI_PROJECT_DIR." 2
 
 SERVICE_ROOT=$(cd "$SERVICE_ROOT" && pwd)