@onlineapps/conn-orch-validator 12.1.0 → 12.2.0

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+### Changed — šablona biz CI: obraz se staví jen na `main`, produkce nasazuje digest z registru (d.671, d.671b; conf image-promotion 001)
+
+Job `build` v `templates/business-service/.gitlab-ci.yml` běží jen na `main` a před stavbou se ptá
+registru, zda tag `:$CI_COMMIT_SHA` už existuje (existuje → nestaví a vypíše digest); tag se nikdy
+nepřepíše. `deploy-production` nebere digest z dotenv artefaktu (`dependencies: []`), ale týmž
+dotazem do registru (`.oa-registry-digest`); když obraz pro commit nenajde, zastaví nasazení
+jmenovanou hláškou a nikdy nestaví náhradu. Fixtury manifestu nesou tentýž blok `oa-ci v1`;
+tvar i tělo dotazu měří `tests/unit/templateImagePromotion.test.js`
+a `tests/unit/templateImagePromotionShell.integration.test.js`.
+
+## [12.1.1] — 2026-09-25
+
+### Fixed — `verify-deploy-uniform.sh`: rada při checkoutu mimo `api_biz/` vede na cestu, kterou šablona skutečně deklaruje (d.899)
+
+Hláška radila `GIT_CLONE_PATH: $CI_BUILDS_DIR/oa-uniform/api_biz/<service>` bez `$CI_CONCURRENT_ID`,
+zatímco `.oa-uniform` v šabloně `.gitlab-ci.yml` deklaruje `$CI_BUILDS_DIR/oa-uniform/$CI_CONCURRENT_ID/api_biz/<service>`.
+Nově radí „make this job extend .oa-uniform" a cituje cestu šablony; `biz-deploy-uniform-gate.bats` čte
+očekávanou cestu ze šablony, takže se hláška a šablona nemohou rozejít.
+
+### Fixed — `verify-deploy-uniform.sh` smaže jen klon, který sám vytvořil; cizí `api/` odmítne a nechá netknutý (d.885)
+
+Šablonový skript brány nasazení odvozuje `API_CHECKOUT="<workspace>/api"` a existující adresář před
+klonem maže, aby runner, který znovu používá svůj builds adresář, neměřil proti zastaralému SSOT. Za
+„svůj" ale uznal každý adresář s `.git` a `config/services.json`, a ty nese KAŽDÝ checkout api
+repozitáře. 2026-09-24 skript spustil vývojář z `api_biz/emailer` na pracovní stanici,
+`<workspace>/api` byl skutečný pracovní strom a skript ho smazal (639 sledovaných souborů; obnoveno).
+
+Skript teď po vlastním `git clone` zapíše do klonu značku `.verify-deploy-uniform.clone`
+(`created-by verify-deploy-uniform.sh <ISO čas> <pid>`). Mazat smí jen adresář, který nese `.git`,
+`config/services.json` A tu značku. Bez značky končí `die` (exit 2): „exists and carries no marker …
+Expected: a clone this script made. Fix: remove it yourself, or run this script only from a CI
+checkout where <workspace>/api is free" a na adresář nesáhne. Přepínač, který by kontrolu vypnul,
+neexistuje (`automation-gates.md` §1 požadavky 3 a 5). URL `file://` se nezakazuje: ochranu nese
+značka a druhé pravidlo pro tutéž věc by bylo druhou kolejí.
+
+RED (`api/tests/scripts/biz-deploy-uniform-gate.bats`, tři nové případy): `not ok 1 an api checkout
+the gate did not make is refused and left exactly as it was` (`[ "$status" -eq 2 ]` failed: skript
+cizí checkout smazal a naklonoval znovu), `not ok 2` a `not ok 3` (značka neexistuje). GREEN: celý
+soubor `1..20`, 20× `ok`, včetně případů se skutečným enginem, které čtou klon se značkou.
+
+### Fixed — konfigurační řádek se severitou `deploy` už neshodí boot služby; start blokuje jen `boot` (d.870)
+
+Krok 2 boot validace (`validateConfig`, řádky `C-SERVICE`, `C-OPS`, `C-CONTRACT`) soudil start podle
+`blocking_severities` uniformy. Ten seznam je ale **verdikt nasaditelnosti**: `runManifest` z něj počítá
+`ok`, tištěné jako DEPLOYABLE / NOT DEPLOYABLE, a pro službu zní `["boot", "deploy"]`. Krok 7 přitom
+soudil start jen podle `boot`. Konfigurační řádek se severitou `deploy` by tedy odmítl start služby, kterou
+konfirmace `biz-service-manifest` 001 §4 nechává běžet („`deploy` — the service **starts**") a jen ji označí
+za nenasaditelnou. Dnes to nikdo neviděl, protože všechny tři řádky kroku 2 mají `boot`. Chyba by se ukázala
+v den, kdy jednomu z nich manifest dá `deploy`.
+
+Otázku „blokuje tento nález start?" teď oba kroky kladou jedné funkci `blocksBoot` nad konstantou
+`BOOT_SEVERITY` (`src/manifest/manifestShape.js`, vedle `SEVERITIES`). `blocking_severities` zůstává tím,
+čím je: seznamem verdiktu uniformy. Tvar výsledku kroků (`valid`, `errors`, `findings`, `deployable`,
+`deployFindings`) se nemění.
+
+RED (`tests/unit/ValidationOrchestrator.manifestStep.test.js`): nový případ „a config row of severity deploy
+does not refuse the boot" `Expected: true / Received: false` na `step2.valid`, `1 failed, 15 passed`. Kontrolní
+případ (týž řádek s `boot` → `valid: false` a přesně jedna chybová zpráva) byl zelený před opravou i po ní.
+
+### Documentation — čísla kroků a citace zrušené hlášky v docblocích (d.870)
+
+- Docblock `runCookbookTests()` říkal „Step 4", ale běh ho loguje jako `Step 5/7`; docblock
+  `validateOperations()` říkal „Step 3" (tedy číslo kroku prostředí), ale běh ho loguje jako `Step 4/7`.
+- Odstavec o zrušeném kroku Readiness (a týž komentář v `tests/unit/ValidationOrchestrator.unit.test.js`)
+  citoval jako přítomnou hlášku kroku 2 `operations.json has no operations defined`, kterou žádný kód nevydává.
+  Teď cituje řádek uniformy `C-OPS`, který tu otázku zodpovídá. Odkaz na řádek nezestárne jako opsaný text.
+
+### Fixed — R6 porovná se SSOT KAŽDÝ pin `@onlineapps/*`, i u knihoven, které infra neinstaluje (d.654, d.654b)
+
+Zúžení na `infraConsumed` přeskakovalo i porovnání ROVNOSTI pinu se SSOT, ne jen otázku
+kompatibility s infra vydáním. Pravidlo R6 přitom žádnou infra klauzuli nemá: služba pinuje
+přesně to, co SSOT deklaruje (`.claude/rules/architecture-principles.md` § Version pinning).
+`notGated` proto **už není výjimka z porovnání, jen informace** o tom, kterou VĚTU nález
+dostane — infra balíček „biz pins X, infra ships Y", balíček bez infra konzumenta „service
+<jméno> pins X, the platform library SSOT declares Y … Fix: npm install <pkg>@Y --save-exact".
+Zelený řádek navíc říká, kolik pinů se doopravdy porovnalo, aby se coverage brány nedala
+odhadnout z názvu druhého seznamu.
+
+**Nahrazuje chování popsané u d.413** („`notGated` zůstává pro deklarovaný balíček, který
+infra neinstaluje" — tam byl `notGated` výjimka z porovnání; od d.654 už není). Položka
+vydané verze zůstává, jak byla: popisuje, co ta verze dělala.
+
+Změřeno nad `api_biz/ingest` (13 pinů `@onlineapps/*`, SSOT deklaruje 28 knihoven a
+`infraConsumed` 7) — PŘED (vydaný validátor 12.1.0): `not gated (no infra service installs
+these): …8 balíčků…` + `OK verify-lib-compat — 5 pin(s) match the platform library set`;
+PO: `no infra comparison (no infra service installs these; their SSOT pin is compared all
+the same): …8 balíčků…` + `OK verify-lib-compat — 13 pin(s) match the platform library
+SSOT, 5 of them also compared against the infra library set`. Falzifikace na kopii
+`package.json` s `@onlineapps/service-wrapper` 10.1.2 proti SSOT 10.1.1 (balíček, který
+žádná infra služba neinstaluje): 12.1.0 exit 0 „5 pin(s) match", nový validátor exit 1
+s jmenovaným nálezem a opravou. Nedotčená kopie dál exit 0.
+
 ## [12.1.0] — 2026-09-18
 
 ### Fixed — lint, který se odmítl spustit, je NOT RUN, ne šest nálezů o dokumentaci (d.632, W632)

package/package.json

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

package/src/ValidationOrchestrator.js

@@ -24,6 +24,21 @@ const { loadManifest, DEFAULT_MANIFEST_PATH } = require('./manifest/loadManifest
 const { runManifest } = require('./manifest/runManifest');
 const { resolveWorkspaceRoot } = require('./manifest/workspaceRoot');
 const { renderBanner, describeFinding } = require('./manifest/report');
+const { BOOT_SEVERITY } = require('./manifest/manifestShape');
+
+/**
+ * Whether a finding refuses the service's start — the one question steps 2 and
+ * 7 both ask, so they ask it here (`.claude/rules/change-discipline.md` § One
+ * rail per concern). Until d.870 step 2 answered it with the uniform's
+ * `blocking_severities`, which is the deployability verdict and names `deploy`
+ * as well, while step 7 answered `boot` alone: a config row given `deploy`
+ * would have refused a start that confirmation `biz-service-manifest` 001 §4
+ * says goes ahead.
+ *
+ * @param {{severity: string}} finding
+ * @returns {boolean}
+ */
+const blocksBoot = (finding) => finding.severity === BOOT_SEVERITY;
 const { buildDeployabilitySignal, writeDeployabilitySignal } = require('./manifest/deployabilitySignal');
 const { isGitCheckout, NOT_A_CHECKOUT } = require('./manifest/gitCheckout');
 
@@ -392,8 +407,8 @@ class ValidationOrchestrator {
    *     (handler presence and shape, bundle_scope, input, output, the retired
    *     v2 fields) — the two loops were textual copies of one another.
    *   - Its only two extra guards, "operations must be an object" and "no
-   *     operations defined", are step 2's `operations.json has no operations
-   *     defined`.
+   *     operations defined", are answered by step 2 through the uniform row
+   *     `C-OPS`.
    *   - Run against a valid baseline plus 13 mutations covering every rule,
    *     its verdict equalled `step2 && step3` in all 14 cases. Against the
    *     eight live biz services it emitted one check, scored 80 out of a
@@ -651,9 +666,13 @@ class ValidationOrchestrator {
    * leaves them out, because they are answered, not because they stopped
    * mattering.
    *
-   * Which severity fails the boot is the uniform's own list, never a constant
-   * here — a service raises `boot`, a library `publish` (`api/shared/TODO.md`
-   * §0.2b-15).
+   * Only a `boot` finding fails the start (`blocksBoot`, the same question
+   * step 7 asks). The uniform's `blocking_severities` is a different list: the
+   * deployability verdict, `["boot", "deploy"]` for a service — a `deploy` row
+   * here is reported, and the service starts undeployable (confirmation
+   * `biz-service-manifest` 001 §4; d.870). This step only ever runs the service
+   * uniform (`manifestRun()` loads `DEFAULT_MANIFEST_PATH`), so no library
+   * severity reaches it.
    *
    * @returns {{valid: boolean, errors: string[], findings: object[]}}
    */
@@ -661,7 +680,7 @@ class ValidationOrchestrator {
     try {
       const run = this.manifestRun();
       const findings = run.findings.filter((finding) => CONFIG_STEP_ROWS.includes(finding.id));
-      const blocking = findings.filter((finding) => run.blockingSeverities.includes(finding.severity));
+      const blocking = findings.filter(blocksBoot);
 
       this.logger.info(`[ValidationOrchestrator] ✓ Config files: ${blocking.length === 0 ? 'PASS' : 'FAIL'}`);
       return {
@@ -701,7 +720,7 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 3: Validate operations compliance (v3 — handler registry dispatch).
+   * Step 4: Validate operations compliance (v3 — handler registry dispatch).
    * Required per operation: handler ('handlers/<path>#<export>'), bundle_scope, input, output.
    * Forbidden (v2): endpoint, method, path.
    * Warned about: a missing `description` — inherited from the removed
@@ -767,7 +786,7 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 4: Run cookbook tests via CookbookTestRunner (v3 handler dispatch).
+   * Step 5: Run cookbook tests via CookbookTestRunner (v3 handler dispatch).
    * Operations must declare a `handler` in operations.json; the runner
    * loads the module via `require()` and calls the exported function
    * in-process. Failures fail this validation step.
@@ -1003,7 +1022,7 @@ class ValidationOrchestrator {
       });
 
       const findings = result.findings.filter((finding) => !CONFIG_STEP_ROWS.includes(finding.id));
-      const bootFindings = findings.filter((finding) => finding.severity === 'boot');
+      const bootFindings = findings.filter(blocksBoot);
 
       return {
         valid: bootFindings.length === 0,

package/src/cli/biz-ci-gate.js

@@ -467,8 +467,13 @@ async function runVerifyLibCompat(options) {
   const librarySet = await loadLibrarySet(options.libraries);
   const result = checkLibCompat(pkg, librarySet);
 
+  // What is skipped for these is the INFRA comparison, and nothing else: since
+  // d.654 their pin is held against the SSOT like every other. The line used to
+  // read "not gated", which after d.654 told the reader the opposite of what
+  // the run did.
   if (result.notGated.length > 0) {
-    process.stdout.write(`[BizCiGate] not gated (no infra service installs these): ${result.notGated.join(', ')}\n`);
+    process.stdout.write('[BizCiGate] no infra comparison (no infra service installs these; their SSOT pin '
+      + `is compared all the same): ${result.notGated.join(', ')}\n`);
   }
   if (!result.ok) {
     for (const violation of result.violations) {
@@ -476,7 +481,14 @@ async function runVerifyLibCompat(options) {
     }
     process.exit(1);
   }
-  process.stdout.write(`[BizCiGate] OK verify-lib-compat — ${result.gated.length} pin(s) match the platform library set\n`);
+  // Two numbers, because the run answers two questions and a single count
+  // could only ever be true of one of them: how many pins were held against the
+  // SSOT (all of them, since d.654), and how many of those infra also installs,
+  // which is the compatibility half. Both come from the rule module's own
+  // lists, never counted again here (`.claude/rules/automation-gates.md` §5 —
+  // a coverage sentence smaller than the coverage is a false signal).
+  process.stdout.write(`[BizCiGate] OK verify-lib-compat — ${result.compared.length} pin(s) match the platform `
+    + `library SSOT, ${result.gated.length} of them also compared against the infra library set\n`);
 }
 
 async function runVerifyContract(options) {

package/src/manifest/manifestShape.js

@@ -21,16 +21,26 @@
 
 const { walkManifest, collectRows, isPlainObject } = require('./walk');
 
+/**
+ * The one severity that refuses a service's start (001 §4). Every other
+ * consequence leaves the service running: `deploy` makes it undeployable,
+ * `publish` belongs to a library, which has no start at all, and `warn` stops
+ * nothing. It is NOT the uniform's `blocking_severities` — that list is the
+ * VERDICT (DEPLOYABLE / PUBLISHABLE, `runManifest` turns it into `ok`), and for
+ * a service it names `deploy` too (d.870).
+ */
+const BOOT_SEVERITY = 'boot';
+
+/** The one severity that stops nothing: it is printed in the table and nowhere else. */
+const WARN_SEVERITY = 'warn';
+
 /**
  * The consequences a row may carry, and no others. `boot` and `deploy` are the
  * service uniform's (001 §4); `publish` is the library uniform's — a library has
  * no boot, and the choke point nothing reaches a service past is
  * `scripts/publish-library.sh` (002 §10).
  */
-const SEVERITIES = Object.freeze(['boot', 'deploy', 'publish', 'warn']);
-
-/** The one severity that stops nothing: it is printed in the table and nowhere else. */
-const WARN_SEVERITY = 'warn';
+const SEVERITIES = Object.freeze([BOOT_SEVERITY, 'deploy', 'publish', WARN_SEVERITY]);
 
 /** Which severities a uniform may declare as blocking — every consequence except `warn`. */
 const BLOCKING_CANDIDATES = Object.freeze(SEVERITIES.filter((severity) => severity !== WARN_SEVERITY));
@@ -435,6 +445,7 @@ module.exports = {
   rowNeedsWorkspace,
   describeFromProblem,
   SEVERITIES,
+  BOOT_SEVERITY,
   CHECK_SCOPES,
   WORKSPACE_DEPENDENT_SCOPES,
   BLOCKING_CANDIDATES,

package/src/utils/libCompat.js

@@ -7,26 +7,34 @@
  * matches the version the platform declares. Mismatch means the service was
  * built against a different platform contract than the one it will run on.
  *
- * Only packages at least one infra service actually installs are compared: the
- * SSOT lists biz-only packages too, and for those there is no infra version to
- * diverge from, so asking "does this match what infra ships" has no answer.
- * The SSOT carries that set as `infraConsumed`. A bare version map has no such
- * list — a platform-release entry records what was deployed, so everything in
- * it is by definition shipped and must match.
+ * EVERY package the SSOT declares and the service pins is compared against the
+ * declared version: R6's rule is that a service pins exactly what the SSOT
+ * declares (`.claude/rules/architecture-principles.md` § Version pinning), and
+ * that sentence carries no infra clause. What the `infraConsumed` list decides
+ * is which SENTENCE a stale pin gets, because the two say different things:
  *
- * That narrowing covers a package the SSOT DECLARES and infra does not install.
- * A package the SSOT declares in NEITHER list is a different thing: not
- * biz-only, but unknown to the platform. R6's rule is that a service pins
- * exactly what the SSOT declares (`.claude/rules/architecture-principles.md`
- * § Version pinning), and for an undeclared package there is no such version at
- * all — so it is refused, never narrowed away. Passing it would be a fallback
- * to "not gated" (principle 3), and it would let a typo or a retired package
- * name travel into an image with the gate reporting OK (measured 2026-09-14).
+ *   - infra installs the package  → biz and infra run different code against
+ *     one contract, and the fix may be to deploy the matching infra release;
+ *   - no infra service installs it → there is no infra version to diverge
+ *     from, so the only statement left is the SSOT one: this pin is not what
+ *     the platform declares, and the fix is to re-pin.
  *
- * The narrowing decides one thing only: which packages are COMPARED against an
- * infra version. It never relaxes the exact-pin rule, which `^`, `~` and
- * `latest` break in EVERY `@onlineapps/*` dependency, gated or not
- * (`.claude/rules/architecture-principles.md` § Version pinning) — a floating
+ * Until 2026-09-18 (W651) `infraConsumed` decided more than that: a package no
+ * infra service installs skipped the version comparison altogether. Measured
+ * then: 20 of the 28 SSOT packages are biz-only, so for most of a service's
+ * pins a biz pipeline compared nothing at all, and a service could ship months
+ * behind the platform with a green gate. A bare version map has no such list —
+ * a platform-release entry records what was deployed, so everything in it is by
+ * definition shipped, and every mismatch is a compatibility one.
+ *
+ * A package the SSOT declares in NEITHER list is a different thing again: not
+ * biz-only, but unknown to the platform — there is no version to pin against at
+ * all, so it is refused, never narrowed away. Passing it would be a fallback to
+ * "not gated" (principle 3), and it would let a typo or a retired package name
+ * travel into an image with the gate reporting OK (measured 2026-09-14).
+ *
+ * The narrowing never relaxes the exact-pin rule either, which `^`, `~` and
+ * `latest` break in EVERY `@onlineapps/*` dependency, gated or not — a floating
  * range makes the same commit install different code on different days whether
  * or not infra happens to ship that package too. Until 2026-09-15 (W413) the
  * exactness test sat inside the gated branch, so a biz-only pin could float
@@ -76,12 +84,39 @@ function normalizeLibrarySet(raw) {
   return { versions: raw, infraConsumed: null };
 }
 
+/**
+ * The service a finding belongs to, taken from its package.json.
+ *
+ * The SSOT-pin finding names the service, because the cross-repository audit
+ * path (`api/scripts/ci/verify-lib-compat.mjs`) reports several repositories in
+ * one run. A package.json without a name is invalid input — npm requires the
+ * field — so it is refused with an actionable message rather than rendered as
+ * "service undefined".
+ */
+function serviceNameOf(pkg) {
+  const name = pkg?.name;
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('[LibCompat] Service package.json declares no "name" - a pin finding must say which '
+      + 'service carries the pin. Fix: add a "name" field to the service package.json.');
+  }
+  return name;
+}
+
 /**
  * Compare a package.json against the platform library set.
  *
+ * `compared` is what the gate may claim as coverage: the packages whose
+ * version was actually held against the declared one. It is appended by the
+ * comparing loop itself, never recomputed from the other two lists by a
+ * renderer — a second derivation of one fact is the drift
+ * `.claude/rules/change-discipline.md` § One rail per concern forbids, and
+ * `gated ∪ notGated` is NOT the same set: a caret pin and a package the SSOT
+ * declares nowhere are classified and then refused before any comparison
+ * happens.
+ *
  * @param {object} pkg parsed package.json of the biz service
  * @param {object} librarySet committed SSOT shape or bare version map
- * @returns {{ok: boolean, gated: string[], notGated: string[], violations: Array<{package: string, message: string}>}}
+ * @returns {{ok: boolean, gated: string[], notGated: string[], compared: string[], violations: Array<{package: string, message: string}>}}
  */
 function checkLibCompat(pkg, librarySet) {
   const { versions, infraConsumed } = normalizeLibrarySet(librarySet);
@@ -91,6 +126,7 @@ function checkLibCompat(pkg, librarySet) {
 
   const gated = [];
   const notGated = [];
+  const compared = [];
   const violations = [];
 
   for (const [name, version] of ours) {
@@ -133,13 +169,23 @@ function checkLibCompat(pkg, librarySet) {
       continue;
     }
 
-    if (bizOnly) continue;
+    // The equality comparison is unconditional, for the same reason the
+    // exactness test above is: R6 proves a service pins exactly what the SSOT
+    // declares, and the SSOT declares a version for the biz-only packages too.
+    // Only the sentence differs — there is no infra release to deploy for a
+    // package no infra service installs, so naming one would send the reader
+    // after a fix that does not exist.
+    compared.push(name);
 
     if (declared !== version) {
       violations.push({
         package: name,
-        message: `${name}: biz pins ${version}, infra ships ${declared} — `
-          + 'rebuild the service against the current platform, or deploy the matching infra release first.'
+        message: bizOnly
+          ? `${name}: service ${serviceNameOf(pkg)} pins ${version}, the platform library SSOT declares `
+            + `${declared} — a service pins exactly what the SSOT declares, whether or not an infra service `
+            + `installs the package. Fix: npm install ${name}@${declared} --save-exact.`
+          : `${name}: biz pins ${version}, infra ships ${declared} — `
+            + 'rebuild the service against the current platform, or deploy the matching infra release first.'
       });
     }
   }
@@ -148,6 +194,7 @@ function checkLibCompat(pkg, librarySet) {
     ok: violations.length === 0,
     gated,
     notGated,
+    compared,
     violations
   };
 }

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

@@ -1,15 +1,17 @@
 # --- oa-ci v1
 # 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), the uniform gate that runs on every
-# pipeline (job validate-uniform, confirmation biz-service-manifest 010) and
-# again before the SSH step as the binding instance (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.
+# pipelines run at all, how a service is built - ONCE, on main, never again on
+# production (confirmation image-promotion 001) - how its image is identified
+# (R5), how that one image's digest reaches the deploy (R1/R2), the uniform gate
+# that runs on every pipeline (job validate-uniform, confirmation
+# biz-service-manifest 010) and again before the SSH step as the binding instance
+# (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
@@ -87,6 +89,126 @@ variables:
     # runner this job carries onto the box comes from that same clone.
     API_UNIFORM_REF_DEPLOY: production
 
+# The ONE question this pipeline asks the container registry (confirmation
+# image-promotion 001): is $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA there, and under
+# which digest? Two jobs need the answer for two different reasons - build, so
+# that a tag already written is never overwritten; deploy-production, because a
+# dotenv artefact does not cross pipelines and production deploys the image main
+# built - and both read it from the registry, the only place both pipelines can
+# see. One question, one implementation: a second copy of this query would be a
+# second rail over one fact (.claude/rules/change-discipline.md § One rail per
+# concern), and the two would answer differently the day one of them was fixed.
+#
+# A hidden key is a declaration and never a job - GitLab runs nothing whose name
+# starts with a dot - so both jobs pull the body in with !reference.
+#
+#   In:  OA_DIGEST_MODE - who is asking, because a missing image means something
+#        different to each of them. "optional": the build's first question, and
+#        an absent tag is the ordinary answer. "build": the build's binding read
+#        after it has built or reused, where an absent tag is a defect. "deploy":
+#        production, where an absent tag is a deploy that must not happen.
+#   Out: OA_IMAGE_PRESENT   - "yes" or "no"
+#        BIZ_IMAGE_DIGEST   - sha256:<64 hex> when present, empty when not.
+#
+# A boolean would not do: the two callers that REQUIRE an image need two
+# different sentences, and one message covering both would name neither the
+# situation nor the fix (architecture-principles.md §5).
+#
+# curl and jq are a declared precondition, not an assumption: the body checks for
+# them before it asks anything (automation-gates.md §2). The deploy job installs
+# them for the post-deploy gate already; the build job's image is alpine and
+# carries neither, so it adds them in a before_script of its own.
+.oa-registry-digest:
+  script:
+    - |
+      # oa-registry-digest
+      for oa_tool in curl jq; do
+        if ! command -v "$oa_tool" > /dev/null 2>&1; then
+          echo "[registry] FATAL: $oa_tool is not on PATH, and the image of this commit can only be found by asking the registry. Expected: curl and jq in this job's image. Fix: add 'apk add --no-cache curl jq' to this job's before_script." >&2
+          exit 1
+        fi
+      done
+      case "${OA_DIGEST_MODE:-}" in
+        optional|build|deploy) ;;
+        *)
+          echo "[registry] FATAL: OA_DIGEST_MODE is '${OA_DIGEST_MODE:-}', and this query has to know what a commit with no image means to the job asking. Expected: 'optional' (the build's first question), 'build' (its binding read after building) or 'deploy' (production). Fix: declare OA_DIGEST_MODE in this job's variables." >&2
+          exit 1 ;;
+      esac
+      # A pull token for THIS project, from this job's own CI_JOB_TOKEN. Both
+      # calls take their credentials AND their URL on stdin (--config -): an
+      # argument stands in the runner's process table for the length of the call,
+      # which is the same reason the registry login below takes its password
+      # there rather than on a command line.
+      oa_exit=0
+      oa_token_json=$(curl --silent --show-error --fail --config - <<CFG
+      user = "gitlab-ci-token:$CI_JOB_TOKEN"
+      url = "$CI_SERVER_URL/jwt/auth?service=container_registry&scope=repository:$CI_PROJECT_PATH:pull"
+      CFG
+      ) || oa_exit=$?
+      if [ "$oa_exit" != "0" ]; then
+        echo "[registry] FATAL: no pull token for $CI_PROJECT_PATH - $CI_SERVER_URL/jwt/auth exited $oa_exit. Expected: a JSON body carrying .token for scope repository:$CI_PROJECT_PATH:pull. Fix: re-run once GitLab answers; this job never continues without a token." >&2
+        exit 1
+      fi
+      oa_token=$(printf '%s' "$oa_token_json" | jq -r '.token // empty')
+      if [ -z "$oa_token" ]; then
+        echo "[registry] FATAL: the token endpoint answered without a .token for $CI_PROJECT_PATH. Expected: {\"token\":\"…\"} for scope repository:$CI_PROJECT_PATH:pull. Fix: check that this project's CI job token may pull its own registry." >&2
+        exit 1
+      fi
+      # HEAD, because the digest is a HEADER: the registry answers
+      # Docker-Content-Digest for a tag without sending the manifest at all. All
+      # four media types are offered, so a single-platform image and an index
+      # both answer with their own digest instead of 406.
+      oa_headers=$(mktemp)
+      oa_exit=0
+      oa_status=$(curl --silent --show-error --head --output /dev/null \
+        --dump-header "$oa_headers" --write-out '%{http_code}' --config - <<CFG
+      header = "Authorization: Bearer $oa_token"
+      header = "Accept: application/vnd.docker.distribution.manifest.v2+json"
+      header = "Accept: application/vnd.oci.image.manifest.v1+json"
+      header = "Accept: application/vnd.docker.distribution.manifest.list.v2+json"
+      header = "Accept: application/vnd.oci.image.index.v1+json"
+      url = "https://$CI_REGISTRY/v2/$CI_PROJECT_PATH/manifests/$CI_COMMIT_SHA"
+      CFG
+      ) || oa_exit=$?
+      if [ "$oa_exit" != "0" ]; then
+        rm -f "$oa_headers"
+        echo "[registry] FATAL: the registry did not answer - HEAD https://$CI_REGISTRY/v2/$CI_PROJECT_PATH/manifests/$CI_COMMIT_SHA, curl exited $oa_exit. Expected: HTTP 200 (the tag is there) or 404 (it is not). Fix: re-run this job once $CI_REGISTRY is reachable - a registry that could not answer is not a registry that said no." >&2
+        exit 1
+      fi
+      # Header names are case-insensitive and the value is lowercase hex either
+      # way, so the whole file is lowercased rather than the match loosened.
+      oa_digest=$(tr '[:upper:]' '[:lower:]' < "$oa_headers" | sed -n 's/^docker-content-digest:[[:space:]]*//p' | tr -d '\r' | head -n 1)
+      rm -f "$oa_headers"
+      case "$oa_status" in
+        200)
+          BIZ_IMAGE_DIGEST="$oa_digest"
+          if ! printf '%s' "${BIZ_IMAGE_DIGEST:-}" | grep -qE '^sha256:[0-9a-f]{64}$'; then
+            echo "[registry] FATAL: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA is in the registry and its Docker-Content-Digest reads '$BIZ_IMAGE_DIGEST' - expected sha256:<64 hex>, the immutable target R1 pins the production compose to. Fix: re-run this job; if it repeats, the registry is answering a shape this platform does not deploy." >&2
+            exit 1
+          fi
+          OA_IMAGE_PRESENT=yes
+          echo "[registry] $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -> $BIZ_IMAGE_DIGEST" ;;
+        404)
+          OA_IMAGE_PRESENT=no
+          BIZ_IMAGE_DIGEST=""
+          # Each caller is told what ITS absent image means, because the three
+          # situations have three different fixes.
+          case "$OA_DIGEST_MODE" in
+            deploy)
+              echo "[deploy] No image for this commit - the registry holds no $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA, so there is nothing main built for production to promote. Expected: the image the main pipeline of this same commit built and pushed (confirmation image-promotion 001). Fix: run a green pipeline on main over $CI_COMMIT_SHA first, then fast-forward production onto it - this deploy never builds a substitute." >&2
+              exit 1 ;;
+            build)
+              echo "[build] FATAL: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA is not in the registry after this job did its work - either the push reported success and the registry does not hold it, or the tag this job found at its start is gone. Expected: the tag, since the digest of THIS build is what the production deploy will read back. Fix: re-run this job; if it repeats, the registry is accepting pushes it does not store." >&2
+              exit 1 ;;
+            *)
+              echo "[registry] $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA is not in the registry yet" ;;
+          esac ;;
+        *)
+          echo "[registry] FATAL: HEAD https://$CI_REGISTRY/v2/$CI_PROJECT_PATH/manifests/$CI_COMMIT_SHA answered HTTP $oa_status - expected 200 (the tag is there) or 404 (it is not). Fix: re-run once the registry answers one of those; this job never reads any other answer as an absent image." >&2
+          exit 1 ;;
+      esac
+      # end oa-registry-digest
+
 # The uniform of THIS commit, on every pipeline - confirmation
 # biz-service-manifest 010. Entry 008 places the BINDING run before the SSH step
 # of a production deploy; it never said that is the only place it runs, and read
@@ -121,39 +243,68 @@ validate-uniform:
     - if: $CI_COMMIT_BRANCH == "devel"
     - if: $CI_COMMIT_BRANCH == "production"
 
+# The image of a commit is built HERE and nowhere else (confirmation
+# image-promotion 001 point 1). production does not build: measured on
+# biz-pdfgen 59b2d59 on 2026-09-19, both branches pushed the same tag :<sha> and
+# the second push overwrote the first, so production ran sha256:1b2a136f… while
+# what main had tested was sha256:5f62e220… and was by then reachable under no
+# tag at all.
 build:
   stage: build
   image: docker:24
   services:
     - docker:24-dind
+  variables:
+    # A tag already in the registry is the ordinary case here (a re-run of this
+    # pipeline), never a defect - so the query below answers and the job decides.
+    # The SECOND question this job asks, after it has built or reused, is asked
+    # in mode "build", where an absent tag is a defect.
+    OA_DIGEST_MODE: "optional"
+  before_script:
+    # docker:24 is alpine and carries neither: the registry query needs both, and
+    # says so by name if they are missing.
+    - apk add --no-cache curl jq
   script:
-    # A password on a command line stands in the runner's process table for the
-    # length of the build and in every trace that echoes the command. The deploy
-    # host's own login has read it from stdin since it was written; both ends of
-    # one login now agree.
-    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
-    - docker build --target production -t $IMAGE -t $IMAGE_LATEST .
-    - docker push $IMAGE
-    - docker push $IMAGE_LATEST
-    # R1: the deploy target is the digest, and it exists only after the push.
+    - !reference [.oa-registry-digest, script]
     - |
-      # --format is not honoured by the buildx on the runner: it prints the whole
-      # descriptor (Name/MediaType/Digest), so the digest would be captured
-      # multi-line and build.env rejected as an invalid dotenv artifact. Parse
-      # the Digest field.
-      BIZ_IMAGE_DIGEST=$(docker buildx imagetools inspect "$IMAGE" | awk '/^Digest:/ { print $2; exit }')
-      if ! printf '%s' "$BIZ_IMAGE_DIGEST" | grep -qE '^sha256:[0-9a-f]{64}$'; then
-        echo "[build] FATAL: no valid digest resolved for $IMAGE - got '$BIZ_IMAGE_DIGEST', expected sha256:<64 hex>. The deploy would have no immutable target. Fix: confirm the push succeeded and that buildx can read $CI_REGISTRY." >&2
-        exit 1
+      if [ "$OA_IMAGE_PRESENT" = "yes" ]; then
+        # :<sha> is written once and never overwritten (image-promotion 001): a
+        # re-run reuses the image this commit already has, and leaves :latest
+        # where it is - re-running an older pipeline must not drag the moving tag
+        # backwards. Said out loud, because a step that decided not to work must
+        # not read like one that worked (automation-gates.md §5).
+        echo "[build] tag :$CI_COMMIT_SHA is already in the registry - not building, digest $BIZ_IMAGE_DIGEST"
+      else
+        # A password on a command line stands in the runner's process table for
+        # the length of the build and in every trace that echoes the command. The
+        # deploy host's own login has read it from stdin since it was written;
+        # both ends of one login now agree.
+        echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+        docker build --target production -t $IMAGE -t $IMAGE_LATEST .
+        docker push $IMAGE
+        docker push $IMAGE_LATEST
       fi
-      echo "[build] $IMAGE -> $BIZ_IMAGE_DIGEST"
-      echo "BIZ_IMAGE_DIGEST=$BIZ_IMAGE_DIGEST" > build.env
+      # R1: the deploy target is the digest, and BOTH branches now read it from
+      # the registry, with the query above - the one the production deploy will
+      # ask too. `docker buildx imagetools inspect` used to answer it here, which
+      # made two implementations of one question ("what digest does :<sha>
+      # have") in one file (change-discipline.md § One rail per concern). What it
+      # reported was the same manifest digest, because this job builds one
+      # platform (a plain `docker build`, no --platform and no `buildx build
+      # --push`, so no index and no attestations) - but the day those differed,
+      # the pipeline would have proved one digest and promoted another.
+      OA_DIGEST_MODE=build
+    - !reference [.oa-registry-digest, script]
+    # The rest of THIS pipeline sees one digest, whether the image was built now
+    # or written by an earlier run. The production deploy does not read this
+    # artefact - it cannot, being in another pipeline - and asks the registry the
+    # same question instead.
+    - echo "BIZ_IMAGE_DIGEST=$BIZ_IMAGE_DIGEST" > build.env
   artifacts:
     reports:
       dotenv: build.env
   rules:
     - if: $CI_COMMIT_BRANCH == "main"
-    - if: $CI_COMMIT_BRANCH == "production"
 
 secret_detection:
   stage: secret-detection
@@ -177,6 +328,24 @@ deploy-production:
     # and the name is the service's registry identity — the one
     # api/config/services.json carries and the contract files its target under.
     DEPLOY_GATE_TARGETS: "biz:__REGISTRY_NAME__"
+    # A production deploy promotes the image main built for this same commit, so
+    # a commit with none is a deploy that must not happen (confirmation
+    # image-promotion 001 point 1). The query below says so by name and stops.
+    OA_DIGEST_MODE: "deploy"
+  # Nothing this job needs comes from another job. It used to take the digest
+  # from build's dotenv artefact, which is why the two jobs had to be in ONE
+  # pipeline - and on production there is no build job at all (image-promotion
+  # 001). Empty rather than absent: absent means "every artefact of every earlier
+  # stage", and a dotenv from somewhere else could then define BIZ_IMAGE_DIGEST
+  # behind this job's back (architecture-principles.md §8).
+  #
+  # It sits HERE, between two mappings, and not behind the before_script below:
+  # a comment indented under a key is not something the extractor of
+  # api/tests/scripts/biz-deploy-secret-handling.bats can end a literal block on,
+  # so this prose used to be handed to `sh` as part of the script (measured
+  # 2026-09-19 on b94c78e5, two suites red). templateImagePromotion.test.js keeps
+  # that shape now.
+  dependencies: []
   before_script:
     # Preconditions first, before anything is installed or deployed
     # (automation-gates.md §1 requirement 4). The post-deploy gate reads the
@@ -250,8 +419,6 @@ deploy-production:
         echo "  StrictHostKeyChecking yes"
         echo "  UserKnownHostsFile ~/.ssh/known_hosts"
       } > ~/.ssh/config
-  dependencies:
-    - build
   script:
     # The uniform of this checkout, complete, BEFORE anything is deployed
     # (confirmation biz-service-manifest 006 point 3, refined by 008): deploy is
@@ -260,12 +427,11 @@ deploy-production:
     # 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_DEPLOY"
-    # R1: refuse to deploy without the immutable target the build stage published.
-    - |
-      if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
-        echo "[deploy] FATAL: BIZ_IMAGE_DIGEST is empty - the build stage publishes it as a dotenv artifact. Refusing to deploy without an immutable image target." >&2
-        exit 1
-      fi
+    # R1: the immutable target, resolved from the registry for THIS commit. The
+    # digest main proved is the digest production runs, and a commit main never
+    # built stops here with a named message rather than being built now
+    # (image-promotion 001; architecture-principles.md §3 No Fallbacks).
+    - !reference [.oa-registry-digest, script]
     - 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

package/templates/business-service/README.md

@@ -58,8 +58,10 @@ cp config/env-templates/service.env config/env-active/__SERVICE_NAME__.env
 docker compose up -d --build
 
 # 4. Start (production) — the image is pinned by digest, so it is PULLED, never
-#    built here: `docker build` refuses a tag that carries a digest. CI publishes
-#    the value; a manual run has to name the digest it wants.
+#    built here: `docker build` refuses a tag that carries a digest. The image is
+#    built once, by the main pipeline of that commit, and the production deploy
+#    reads its digest back from the registry (docs/80-setup/INSTALL.md §
+#    Production); a manual run has to name the digest it wants.
 BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml pull
 BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
 ```

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

@@ -90,9 +90,37 @@ BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml pull
 BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
 ```
 
-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.
+### One image per commit: built on `main`, promoted to production
+
+The image of a commit is built **once**, by the `build` job of that commit's
+`main` pipeline, and pushed as `:<commit sha>`. That tag is written once and
+never overwritten: a re-run of the same pipeline finds it in the registry, says
+so, and neither builds nor pushes.
+
+A production deploy does not build. It asks the registry for the digest of
+`:<commit sha>` and deploys that — the image `main` tested, by digest
+(requirement R1). A commit whose `main` pipeline never produced one cannot reach
+production: the deploy stops with a message naming the commit, and never builds a
+substitute. The way forward is always the same one — a green `main` pipeline over
+that commit, then a fast-forward of `production` onto it. Owner decision:
+`api/docs/governance/confirmations/image-promotion.md` 001.
+
+Two things this rests on, and both are preconditions rather than details:
+
+- **Registry retention.** The image must still be there when `production`
+  deploys, and when a rollback needs the last green one. A cleanup policy on a
+  biz project may therefore be enabled only together with a rule that never
+  deletes a tag matching a 40-character commit sha; `:latest` and any other
+  moving tag are not part of this and may be cleaned freely.
+- **Rollback reads the same place.** There is no automatic rollback for the first
+  deployments (`api/docs/governance/confirmations/biz-rollback-first-deploy.md`
+  001): the return is the manual runbook step above — `docker compose up` with
+  the digest of the last green commit, read from the registry under that commit's
+  own `:<sha>`. Nothing writes that digest down anywhere else, which is exactly
+  why the retention rule is not optional.
+
+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
 

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

@@ -54,8 +54,11 @@ the service.
   `@onlineapps/*` pins against the platform library set) and the service's
   dependencies installed — the test-coverage half asks the service's own jest
   which files it would run.
-- The build stage publishes the image digest as a dotenv artifact and the deploy
-  stage refuses to run without it; both stages are declared in `.gitlab-ci.yml`.
+- The build stage runs on `main` and builds the image of that commit once; the
+  deploy stage reads the digest of `:<commit sha>` back from the registry and
+  refuses to deploy a commit that has none. Both stages are declared in
+  `.gitlab-ci.yml`, and what each may do is
+  [INSTALL.md § Production](INSTALL.md).
 - Windows is outside the supported matrix.
 
 ## Status

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

@@ -79,7 +79,7 @@ WORKSPACE_ROOT=$(dirname "$CONTAINER_DIR")
 API_CHECKOUT="$WORKSPACE_ROOT/api"
 
 if [ "$(basename "$CONTAINER_DIR")" != "api_biz" ]; then
-  die "The checkout is not in the layout the uniform needs - $SERVICE_ROOT lies in '$(basename "$CONTAINER_DIR")', and the engine answers the rows that read the platform SSOT only for a service under <root>/api_biz/ beside <root>/api. Expected: the job checks this project out there. Fix: in .gitlab-ci.yml set the job variable GIT_CLONE_PATH: \$CI_BUILDS_DIR/oa-uniform/api_biz/<service>, and confirm the runner allows a custom build directory ([runners.custom_build_dir] enabled)." 2
+  die "The checkout is not in the layout the uniform needs - $SERVICE_ROOT lies in '$(basename "$CONTAINER_DIR")', and the engine answers the rows that read the platform SSOT only for a service under <root>/api_biz/ beside <root>/api. Expected: the job checks this project out there. Fix: make this job extend .oa-uniform in .gitlab-ci.yml (it sets GIT_CLONE_PATH: \$CI_BUILDS_DIR/oa-uniform/\$CI_CONCURRENT_ID/api_biz/<service>), and confirm the runner allows a custom build directory ([runners.custom_build_dir] enabled)." 2
 fi
 
 command -v git >/dev/null 2>&1 || die "Missing tool - 'git' does not run, and the api checkout this run reads cannot be fetched without it. Fix: install git in the job image (apk add --no-cache git)." 2
@@ -90,12 +90,24 @@ command -v node >/dev/null 2>&1 || die "Missing tool - 'node' does not run, and
 # Read-only and shallow: the uniform reads files, never history. A runner reuses
 # its builds directory between pipelines, so a checkout left by an earlier run
 # would silently measure this deploy against a stale SSOT — it is removed and
-# fetched again, and only when it is recognisably this script's own artefact.
+# fetched again, and ONLY when this script can prove it made it.
+#
+# The proof is the marker the clone step below writes. `.git` plus
+# `config/services.json` is no proof at all: every checkout of the api repository
+# carries both. On 2026-09-24 the script was run from api_biz/emailer on a
+# workstation, <workspace>/api was the developer's real working tree, it passed
+# that test and was deleted (639 tracked files; d.885). A directory without the
+# marker is somebody's work, so the script refuses and touches nothing
+# (`automation-gates.md` §1 requirement 3, Safe). There is no flag that skips
+# the check: the one systemic path is a free place or a clone this script made.
+CLONE_MARKER=".verify-deploy-uniform.clone"
 if [ -e "$API_CHECKOUT" ]; then
-  if [ -d "$API_CHECKOUT/.git" ] && [ -f "$API_CHECKOUT/config/services.json" ]; then
+  if [ -d "$API_CHECKOUT/.git" ] && [ -f "$API_CHECKOUT/config/services.json" ] \
+    && [ -f "$API_CHECKOUT/$CLONE_MARKER" ] \
+    && head -n 1 "$API_CHECKOUT/$CLONE_MARKER" | grep -q '^created-by verify-deploy-uniform.sh '; then
     rm -rf "$API_CHECKOUT"
   else
-    die "Cannot place the api checkout - $API_CHECKOUT already exists and is not an api clone this script made (no .git and config/services.json). Expected: that path free, or an earlier clone of the api repository. Fix: remove it, or point the job's GIT_CLONE_PATH at a build directory this pipeline owns." 2
+    die "Cannot place the api checkout - $API_CHECKOUT exists and carries no marker $CLONE_MARKER, so it is not a clone this script made, and deleting it could destroy somebody's work. Expected: a clone this script made. Fix: remove it yourself, or run this script only from a CI checkout where <workspace>/api is free (the job's GIT_CLONE_PATH points at a build directory this pipeline owns)." 2
   fi
 fi
 
@@ -106,6 +118,11 @@ if ! git clone --depth 1 --single-branch --branch "$API_REF" "$API_URL" "$API_CH
   die "The api checkout could not be cloned - git clone --branch $API_REF $SAFE_URL failed, so api/config/services.json cannot be read and the uniform would answer a fraction of its rows. A partial answer is not a deploy permit, so this refuses rather than continues. Expected: read access for this pipeline's job token. Fix: in GitLab open the api project, Settings > CI/CD > Job token permissions, and add this project to the allowlist (owner's step, confirmation biz-service-manifest 008 point 2); check also that the ref '$API_REF' exists there." 2
 fi
 
+# The marker is what lets the NEXT run delete this clone, so it is written the
+# moment the clone exists and before anything reads it.
+printf 'created-by verify-deploy-uniform.sh %s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$$" > "$API_CHECKOUT/$CLONE_MARKER" \
+  || die "Cannot mark the api checkout - writing $API_CHECKOUT/$CLONE_MARKER failed, and without it the next run would refuse to replace this clone. Expected: a writable build directory. Fix: check the permissions of $WORKSPACE_ROOT on the runner." 2
+
 # --- the engine -------------------------------------------------------------
 #
 # The pin decides which uniform this service is measured against, so the engine