@onlineapps/conn-orch-validator 11.0.0 → 12.1.0

package/CHANGELOG.md

@@ -4,6 +4,125 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [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)
+
+Řádky dokumentace (`docs-lint`, `docs-lint-clean` → `D-PORT`, `D-NPM`, `D-SCRIPT`, `D-RETIRED`, `D-HEADER`, `D-LINT`): lint
+`lint-biz-docs`, který skončil bez verdiktu (exit 2, pád spawnu, nerozparsovatelný JSON), je NOT RUN na každém řádku, který
+z něj čte, a signál nese `complete: false`; dosud z toho most dělal šest nálezů `deploy` s radami o obsahu dokumentace a
+`complete: true` (změřeno 2026-09-17, CI joby 16572194080 a 16571115198: GitLab Runner zakládá `api_biz/<svc>.tmp` a lint ho
+bral za službu). Důvod NOT RUN nese CELÝ stderr lintu, první řádek první (poslední řádek byla závorka gitu „Stopping at
+filesystem boundary“); `Fix:` se doplní jen když ho hláška lintu nenese. Chybějící `config/biz-docs-lint.tree.json` zůstává
+nálezem (`C-LINT`). Zároveň v api (`6f9d2f2b`): lint i `sync-biz-facts` berou sourozence ze SSOT `config/services.json`
+(`directory` u `enabled`), ne z výpisu `api_biz/` — nedeklarovaný adresář se nečte a řekne se to jednou větou.
+
+### Changed (testy) — třetí živá DB sada přes `liveDatabase.js`; sondy skládají dočasný adresář z `os.tmpdir()` (d.620b, W620b)
+
+`bizCiGateCli.setupDbAccount.integration` (blok „how far the production grant reaches“) bere spojení z
+`tests/helpers/liveDatabase.js`, práce je v `tests/helpers/grantReachProbe.js` a sada je třetí v jobu `test-validator-db`;
+`setupDatabaseProbe.js` a `dbAccountProbe.js` už nepíší do doslovného `/tmp`.
+
+
+### Changed (testy) — živé DB sady databázi deklarují, nehledají; „unwritable root“ se pod rootem předvede (d.628, d.623c, W623)
+
+`setupDatabaseLive.integration` a `dbCiAccount.integration` čtou spojení z `DB_HOST`, `DB_PORT`, `CI_DB_ROOT_USER`,
+`CI_DB_ROOT_PASSWORD` — jména, která čte `biz-ci-gate setup-db-account` — přes jednoho vlastníka `tests/helpers/liveDatabase.js`;
+dosud každá nesla vlastní kopii s vývojovým kontejnerem `gen_mariadb10.5`, sítí `gendb-network` a heslem z gitignorovaného
+`config/env-active/gen-db.env`, takže v CI checkoutu padaly. Bez deklarace se případy registrují jako přeskočené s vytištěným
+důvodem (runner hlásí „27 skipped“, ne „27 passed“); s deklarací se měří a nedostupný server, chybějící klient i chybějící
+`DB_DOCKER_NETWORK` jsou pád. V CI je pouští nový job `test-validator-db` se službou `mariadb:10.5.29` (vlastník 2026-09-18,
+conf `ci-validator-db-job` 001). Lokálně: README § Running the live-database suites. `oaValidateCli.integration` — případ
+„an unwritable service root fails fast“ se pod uid 0 předvádí pod neprivilegovaným účtem stroje místo NOT RUN.
+
+
+### Changed — šablona `init.sh` staví strom z `package-lock.json` (`npm ci`), ne `npm install` (d.629, W629)
+
+`templates/business-service/init.sh` `oa_npm_install()` = `npm ci --no-audit --no-fund`. `npm install --package-lock-only`
+(re-pin v živém bind-mount stromu) přepíše lock i skrytý `node_modules/.package-lock.json`, složky balíčků nechá staré,
+a `npm install` pak hlásí „up to date“ — služba tiše běží na jiné verzi, než pinuje lock a R6 (nález INFRA-monitoring,
+INFRA B137 `28fef3dc` totéž v sedmi infra službách). Podmínka instalace (blok `oa-deps-guard v1`, marker
+`.oa_drive_deps_hash`) ani znění bloku se nemění. Změřeno bez sítě nad lokálním tarballem: složka 1.0.0 × lock 2.0.0 →
+`npm install` „up to date“ (1.0.0), `npm ci` „added 1 package“ (2.0.0). Řádek uniformy `F-INIT` roznáší jen blok, servisní
+`oa_npm_install()` je řádek každé služby — běžících osm se nemění, dostanou ho pokynem. Služba oskládaná ze šablony
+potřebuje `package-lock.json` už při prvním startu: šablona ho neveze, první boot bez něj skončí hlášeným `EUSAGE`.
+
+
+### Fixed — hlavní grant databázového účtu escapuje `_` (d.620, W620)
+
+`databaseAccountSql` escapuje `_` i v hlavním grantu (`` ON `oagen\_x`.* ``), ne jen v CI wildcardu: databázová část
+`GRANT`u je LIKE vzor i bez `%`, takže grant, který dostane každá nasazená služba, otevíral i sousední schéma lišící se
+v tom jednom znaku (`oagen_emailer` → `oagen5emailer`; nález INFRA-DOCS z falzifikace `INSTALL.md`). Escape je jedna
+funkce `escapeSchemaPattern()` použitá na obě věty; `%` ve jméně schématu se odmítá s `Fix:` (žádné platformní jméno ho
+nenese, `\` odmítal už `FORBIDDEN_IN_VALUE`). Změřeno proti živé MariaDB 10.5: před opravou účet přečetl sousedovy řádky,
+po opravě `ERROR 1142 (42000) … SELECT command denied`; vlastní schéma dál čitelné, CI throwaway grant (`oagen\_x\_%`) drží.
+
+
+### Fixed — pozice balíčku ve workspace nese konvenční prefix `api/`, ne jméno adresáře checkoutu (d.625, W625)
+
+`sync/readmeLocation.js` odvozovalo `PACKAGE_IN_WORKSPACE` (a s ním `requiresSiblings` řádku `L-README-REGION`) z adresáře
+NAD checkoutem. GitLab CI klonuje repozitář pod jménem projektu `infra-mono`, takže vznikalo
+`infra-mono/shared/connector/conn-orch-validator`; `resolveWorkspacePath()` rozřeší přes marker jen hlavu `api` a zbytek
+připojí doslova → řetězec neukazoval nikam a běh končil větou `Fix: run with --workspace pointing at a checkout that carries
+infra-mono/…`, kterou nikdo nemůže splnit (`automation-gates.md` §1/4). Pravidlo stojí v hlavičce `manifest/workspaceRoot.js`:
+`api/` na začátku cesty je konvence deklarujícího textu, nikdy jméno adresáře na disku — prefix se proto čte z
+`WORKSPACE_MARKER` (jediný vlastník), ne píše podruhé. Změřeno v obrazu jobu nad jedním stromem pod dvěma jmény: 27 unit
+testů a 6 bats červených pod `infra-mono`, zelené pod `api`; po opravě zelené pod oběma. Štítek souboru na stdout
+`oa-sync-template` dál nese cestu na disku (tam soubor je) — srovnán test, ne výstup.
+
+
+## [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/README.md

@@ -269,6 +269,53 @@ namespace an integration tier builds into (`src/utils/throwawaySchema.js`). The
 `_` is escaped, so the grant stays inside one service — unescaped it is a LIKE
 wildcard, and `oagen_meta_%` would also match `oagen_metadata`.
 
+**The escape belongs to BOTH grants.** The database-name position of a `GRANT`
+is a LIKE pattern whether or not a `%` follows it, so the grant every installed
+service gets is written `` `oagen\_meta`.* `` too: unescaped, it also grants
+`oagen5meta` and every other schema differing in that one character. `%` in a
+schema name is refused rather than escaped — no platform name carries one.
+
+### Running the live-database suites
+
+Two suites of this package measure what a **real** MariaDB does with the SQL the
+package builds — `tests/unit/setupDatabaseLive.integration.test.js` (what
+`ci:gate:setup` leaves in the schema) and `tests/unit/dbCiAccount.integration.test.js`
+(whether the grants above are enough, and still not too much). They are part of
+`npm run test:unit`, and in CI they have a job with a database of its own,
+`test-validator-db` (owner decision
+[`ci-validator-db-job` 001](../../../docs/governance/confirmations/ci-validator-db-job.md)).
+
+Neither suite looks for a database. It is **declared**, under the names this
+package's own CLI reads:
+
+| Variable | What it is |
+|---|---|
+| `DB_HOST` / `DB_PORT` | the server the run measures |
+| `CI_DB_ROOT_USER` / `CI_DB_ROOT_PASSWORD` | its administrative login — the suites create and drop schemas of their own |
+| `DB_DOCKER_NETWORK` | only where no `mariadb` client is on PATH: the docker network the probe is carried in on |
+
+Declare nothing and the suites report **NOT RUN** with that sentence and a `Fix:`
+— they never stand down quietly. Declare a database and it is measured: an
+unreachable server, a missing client and a missing network are failures, so a run
+cannot go green having looked at nothing.
+
+On a developer machine the dev server publishes no port and macOS carries no
+client, so both the network and the credential come from the local environment —
+the password is read out of the gitignored file that owns it, never written into
+the repository:
+
+```bash
+cd api/shared/connector/conn-orch-validator
+DB_HOST=gen_mariadb10.5 DB_PORT=3306 \
+CI_DB_ROOT_USER=root \
+CI_DB_ROOT_PASSWORD="$(grep '^MARIADB_ROOT_PASSWORD=' ../../../config/env-active/gen-db.env | cut -d= -f2-)" \
+DB_DOCKER_NETWORK=gendb-network \
+npx jest tests/unit/setupDatabaseLive.integration.test.js tests/unit/dbCiAccount.integration.test.js
+```
+
+The run prints which server it measured, or why it measured none — that line is
+what tells a green suite that looked from a green suite that did not.
+
 ---
 
 ## Environment contract (`env` block)

package/jest.config.js

@@ -13,6 +13,17 @@ module.exports = {
   testMatch: [
     '**/tests/**/*.test.js'
   ],
+
+  // tests/fixtures/manifest/** holds SIMULATED CHECKOUTS that the manifest
+  // suites read from disk as data, never require. Jest's haste map indexes every
+  // package.json it crawls, so the three fixture workspaces that each carry the
+  // service `biz-alpha` read as three modules of one name and the crawl prints
+  // "Haste module naming collision" on stdout. The reason the fixtures keep
+  // their names, and why the pattern stops at `manifest/` rather than covering
+  // tests/fixtures/ whole, is written once — in the repository's jest.config.js,
+  // beside the same string. This config owns the same exclusion for its own map,
+  // because rootDir here is the package.
+  modulePathIgnorePatterns: ['/tests/fixtures/manifest/'],
   coverageThreshold: {
     global: {
       branches: 80,

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.1.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"

package/src/manifest/checks/docsLintBridge.js

@@ -107,6 +107,50 @@ const LINT_TIMEOUT_MS = 120000;
 /** Room for the JSON of a large tree; the biggest measured today is 54 findings. */
 const LINT_MAX_BUFFER = 32 * 1024 * 1024;
 
+/**
+ * How much of the linter's own output the refusal sentence carries, in
+ * characters. A budget, not a line count: what makes a refusal actionable is the
+ * FIRST line, which is the linter's `[tool] ERROR:` message with its own `Fix:`
+ * in it, and the lines after it are context of falling value. So the first line
+ * is never cut and the rest fills what is left.
+ */
+const REFUSAL_BUDGET = 700;
+
+/** The remedy for a refusal whose own message named none. */
+const REFUSAL_FIX = `Fix: run ${LINT_SCRIPT} over this tree by hand and repair what it reports.`;
+
+/**
+ * What a run that produced no verdict says, from everything the linter printed.
+ *
+ * Until d.632 this read `…split('\n').filter(Boolean).pop()` — the LAST line —
+ * and the last line of the measured failure was git's own aside, `Stopping at
+ * filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set)`. The sentence
+ * that says WHAT the linter refused, and how to repair it, is the first one, so
+ * the reader was handed the footnote and not the message (CI jobs 16572194080,
+ * 16571115198; `.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * @param {{status: number|null, stderr: string, stdout: string}} run the finished process
+ * @returns {string}
+ */
+function describeRefusal({ status, stderr, stdout }) {
+  const lines = String(stderr || stdout || '').split('\n').map((line) => line.trim()).filter(Boolean);
+  const exited = status === null || status === undefined ? 'on a signal' : String(status);
+  if (lines.length === 0) return `the lint exited ${exited} without a verdict and printed nothing. ${REFUSAL_FIX}`;
+
+  let said = lines[0];
+  for (const line of lines.slice(1)) {
+    if (said.length + line.length + 3 > REFUSAL_BUDGET) {
+      said += ' …';
+      break;
+    }
+    said += ` | ${line}`;
+  }
+  // The linter writes its own `Fix:` into the message; a second one beside it
+  // would be this module restating the tool (docblock at the top of this file).
+  // Only a message that named none gets the command.
+  return `the lint exited ${exited} without a verdict — ${said}${said.includes('Fix:') ? '' : `. ${REFUSAL_FIX}`}`;
+}
+
 /**
  * The lint's answers, keyed by what the run was about. One service is linted
  * ONCE however many rows cite it: five rows spawning five processes over the
@@ -296,7 +340,7 @@ function claimantOf(ruleId, rows) {
  * Run the lint over one tree, once.
  *
  * @param {{ lintScript: string, docsDir: string, treeConfig: string }} params absolute paths
- * @returns {{findings: Array<object>, skipped: Array<object>}|{problem: string}}
+ * @returns {{findings: Array<object>, skipped: Array<object>}|{refusal: string}}
  */
 function lintOnce({ lintScript, docsDir, treeConfig }) {
   // `\0` as the escape, never the raw byte: written literally it makes the
@@ -313,7 +357,7 @@ function lintOnce({ lintScript, docsDir, treeConfig }) {
 
 /**
  * @param {{ lintScript: string, docsDir: string, treeConfig: string }} params
- * @returns {{findings: Array<object>, skipped: Array<object>}|{problem: string}}
+ * @returns {{findings: Array<object>, skipped: Array<object>}|{refusal: string}}
  */
 function runLint({ lintScript, docsDir, treeConfig }) {
   const run = spawnSync(process.execPath, [lintScript, ...lintArgumentsFor({ docsDir, treeConfig })], {
@@ -326,23 +370,20 @@ function runLint({ lintScript, docsDir, treeConfig }) {
     maxBuffer: LINT_MAX_BUFFER
   });
 
-  if (run.error) return { problem: `${run.error.message} (${lintScript})` };
+  if (run.error) return { refusal: `the lint could not be started: ${run.error.message} (${lintScript}). ${REFUSAL_FIX}` };
 
   // 0 = clean, 1 = findings; anything else is the lint refusing to run, and its
   // reason is on stderr. A run that ended there is NOT an empty finding list.
-  if (run.status !== 0 && run.status !== 1) {
-    const said = String(run.stderr || run.stdout || '').trim().split('\n').filter(Boolean).pop();
-    return { problem: `the lint exited ${run.status === null ? 'on a signal' : run.status}: ${said || 'no output'}` };
-  }
+  if (run.status !== 0 && run.status !== 1) return { refusal: describeRefusal(run) };
 
   let parsed;
   try {
     parsed = JSON.parse(run.stdout);
   } catch (error) {
-    return { problem: `its JSON output could not be read: ${error.message}` };
+    return { refusal: `the lint exited ${run.status} and its JSON output could not be read: ${error.message}. ${REFUSAL_FIX}` };
   }
   if (!Array.isArray(parsed.findings) || !Array.isArray(parsed.skipped)) {
-    return { problem: 'its JSON output carries no "findings"/"skipped" arrays' };
+    return { refusal: `the lint exited ${run.status} and its JSON output carries no "findings"/"skipped" arrays. ${REFUSAL_FIX}` };
   }
   return { findings: parsed.findings, skipped: parsed.skipped };
 }
@@ -408,13 +449,23 @@ function treeConfigOf(block) {
 /**
  * Ask the lint about one service tree, once, for whichever row is asking.
  *
- * Three answers, and every caller words them in its own sentence: the tree has
- * nothing to lint, the question could not be decided (with the reason), or the
- * lint's own payload.
+ * Four answers, and every caller words them in its own sentence: the tree has
+ * nothing to lint, the question could not be decided because a file with a fix
+ * of its own is missing, the lint REFUSED to run at all, or the lint's own
+ * payload.
+ *
+ * The last two were one answer until d.632, and both became findings. They are
+ * different facts. An absent tree config is a defect of this repository with a
+ * row that owns it (`C-LINT`) and a repair somebody can carry out here, so it
+ * stays a finding. A lint that refused to run measured NOTHING: it decided no
+ * rule, so a row reporting a `deploy` finding about documentation is asserting
+ * something nobody looked at — six of them, in the run this split comes from.
+ * That is NOT RUN (`.claude/rules/automation-gates.md` §5).
  *
  * @param {{ block: object, serviceRoot: string, workspaceRoot: string }} params
  * @returns {{nothingToLint: true}
  *           |{undecidable: {relative: string, reason: string}}
+ *           |{refused: string}
  *           |{answer: {findings: Array<object>, skipped: Array<object>}}}
  */
 function askLint({ block, serviceRoot, workspaceRoot }) {
@@ -442,7 +493,7 @@ function askLint({ block, serviceRoot, workspaceRoot }) {
     docsDir,
     treeConfig
   });
-  if (answer.problem !== undefined) return { undecidable: { relative: DOCS_DIR, reason: answer.problem } };
+  if (answer.refusal !== undefined) return { refused: answer.refusal };
 
   return { answer };
 }
@@ -475,7 +526,7 @@ const docsLint = Object.freeze({
 
   /**
    * @param {{ row: object, block: object, serviceRoot: string, workspaceRoot: string }} params
-   * @returns {Array<{where: string, what: string}>}
+   * @returns {Array<{where: string, what: string}>|{findings: Array<object>, notRun: string}}
    */
   run({ row, block, serviceRoot, workspaceRoot }) {
     const rows = rowsOf(block);
@@ -490,6 +541,9 @@ const docsLint = Object.freeze({
         what: `${row.rule} could not be decided — ${asked.undecidable.reason}`
       }];
     }
+    if (asked.refused !== undefined) {
+      return { findings: [], notRun: `${row.rule} could not be decided — ${asked.refused}` };
+    }
     const answer = asked.answer;
 
     const found = answer.findings
@@ -511,9 +565,10 @@ const docsLint = Object.freeze({
     // The mapping is the linter's own two channels onto this uniform's two: its
     // `findings` are findings, its `skipped` list is the NOT RUN one (that is
     // what `--allow-missing-siblings` fills, and what its own text output prints
-    // as NOT RUN lines). A tree the linter REFUSES outright is neither — that
-    // is `answer.problem` above, and the absent tree config before it, both of
-    // which stay findings with a fix somebody can carry out.
+    // as NOT RUN lines). A tree whose lint REFUSED to run is NOT RUN too, for
+    // the same reason and one branch above (`askLint` § refused); the absent
+    // tree config before it stays a finding, because `C-LINT` owns that file
+    // and the repair is here.
     //
     // The sentence itself is `describeUndecided` above — shared with `D-LINT`,
     // which reports the same absence about the rules no row claims.
@@ -579,6 +634,9 @@ const docsLintClean = Object.freeze({
         what: `no finding could be decided — ${asked.undecidable.reason}`
       }];
     }
+    if (asked.refused !== undefined) {
+      return { findings: [], notRun: `no finding could be decided — ${asked.refused}` };
+    }
     const answer = asked.answer;
 
     const found = errorGraded(answer.findings)
@@ -605,6 +663,7 @@ module.exports = {
   claimantOf,
   citationsOf,
   covers,
+  describeRefusal,
   errorGraded,
   LINT_SCRIPT,
   LINT_DIR

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/sync/readmeLocation.js

@@ -29,7 +29,7 @@ const path = require('path');
 
 const { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
 const {
-  API_CHECKOUT_ROOT, PACKAGE_ROOT: OWN_ROOT, resolveWorkspacePath
+  API_CHECKOUT_ROOT, PACKAGE_ROOT: OWN_ROOT, WORKSPACE_MARKER, resolveWorkspacePath
 } = require('../manifest/workspaceRoot');
 const { KINDS, renderUniformRegion } = require('./readmePointer');
 
@@ -74,6 +74,13 @@ function serviceManifestPath(serviceRoot) {
   return path.join(serviceRoot, 'node_modules', ...selfName().split('/'), SERVICE_MANIFEST_IN_PACKAGE);
 }
 
+/**
+ * The conventional prefix a workspace-relative path uses for the api checkout,
+ * read off the marker that declares it rather than typed a second time here
+ * (`../manifest/workspaceRoot.js`, which owns both the prefix and the marker).
+ */
+const [API_PREFIX] = WORKSPACE_MARKER.split('/');
+
 /**
  * Where this package lies inside its own workspace, workspace-relative — or null
  * when it lies in no checkout at all (an installed copy, a service container).
@@ -84,10 +91,25 @@ function serviceManifestPath(serviceRoot) {
  * at the manifest AS IT LIES IN THAT CHECKOUT, and where there is no copy there
  * is no link — which is a question the run could not answer, never a package
  * that passed (`.claude/rules/automation-gates.md` §5).
+ *
+ * The head of that path is the CONVENTION `api/`, never the name the checkout
+ * happens to wear on disk — the rule `workspaceRoot.js` states in its header and
+ * implements in `resolveWorkspacePath()`, which is the function this string is
+ * handed to. Deriving it as "the directory above the checkout, then the checkout"
+ * broke that rule wherever the checkout is named something else: GitLab CI checks
+ * this repository out as `infra-mono`, so the string became
+ * `infra-mono/shared/connector/conn-orch-validator`, which `resolveWorkspacePath`
+ * joins literally — pointing at nothing in every workspace, including the fixture
+ * and sandbox trees the suites build. Measured 2026-09-17 in the job's own image,
+ * one tree under two names: under `infra-mono` the run died with
+ * `Fix: run with --workspace pointing at a checkout that carries
+ * infra-mono/shared/connector/conn-orch-validator` — an instruction nobody can
+ * carry out (`.claude/rules/automation-gates.md` §1 requirement 4) — while the
+ * same tree named `api` was green.
  */
 const PACKAGE_IN_WORKSPACE = API_CHECKOUT_ROOT === null
   ? null
-  : path.relative(path.dirname(API_CHECKOUT_ROOT), OWN_ROOT).split(path.sep).join('/');
+  : [API_PREFIX, ...path.relative(API_CHECKOUT_ROOT, OWN_ROOT).split(path.sep)].join('/');
 
 /**
  * The manifest as it lies in the workspace being read, whichever of the two it

package/src/utils/dbAccountGrants.js

@@ -33,6 +33,24 @@
  * what keeps the grant inside one service, and it is the difference
  * `tests/unit/dbAccountGrants.test.js` measures.
  *
+ * ## The escape belongs to BOTH grants, not only the wildcard one
+ *
+ * The database-name position of a `GRANT` is read as a LIKE pattern whether or
+ * not a `%` follows it, so `` ON `oagen_emailer`.* `` — the grant EVERY
+ * installed service gets — also grants `oagen5emailer` and every other schema
+ * differing in that one character. One escape function therefore runs on the
+ * schema name before either statement is built; the production runbook
+ * (`api/docs/setup/INSTALL.md` § the account and its grants, `schema_grant`)
+ * already escaped it, and a definition laxer than the runbook installing from it
+ * is the wrong way round. Measured against the dev server in
+ * `tests/unit/bizCiGateCli.setupDbAccount.integration.test.js`: with the
+ * unescaped grant the account reads the neighbour's rows; with it, `ERROR 1142`.
+ *
+ * `%` — the other wildcard of that position — is REFUSED rather than escaped,
+ * for the reason the comment above `FORBIDDEN_IN_VALUE` gives: no platform
+ * schema name carries one, so a value that does came from somewhere it should
+ * not have. `_` cannot be refused the same way: every platform name has one.
+ *
  * Production never gets that grant: it installs one schema, and a wildcard there
  * would be a standing privilege nobody asked for.
  *
@@ -84,6 +102,43 @@ function requireValue(value, name, fix) {
   return value;
 }
 
+/**
+ * The one escape of this file, used by every grant it builds.
+ *
+ * MariaDB reads the database-name position of a `GRANT` as a LIKE pattern, so
+ * `_` there matches any single character. Every platform schema is
+ * `oagen_<shortname>`, which means every unescaped grant this package could
+ * build would reach a schema nobody named.
+ *
+ * `%` is not escaped here — `requireGrantableSchema` refuses it before this
+ * runs, so the only wildcard left to neutralise is `_`.
+ *
+ * @param {string} schema a schema name already checked by `requireGrantableSchema`
+ * @returns {string} the same name as a LIKE pattern matching only itself
+ */
+function escapeSchemaPattern(schema) {
+  return schema.replace(/_/g, '\\_');
+}
+
+/**
+ * A schema name this file can turn into a grant that reaches that schema ALONE.
+ *
+ * `requireValue` already refuses the backslash (an escape nobody wrote here) and
+ * the quoting characters. This adds the one character that is neither a quoting
+ * problem nor escapable without changing what the name means: `%`.
+ */
+function requireGrantableSchema(schema, fix) {
+  requireValue(schema, 'schema', fix);
+  if (schema.includes('%')) {
+    throw new Error('[DbAccountGrants] schema carries `%`, which the database-name position of a GRANT '
+      + `reads as a wildcard: ${JSON.stringify(schema)}.\n`
+      + '       A grant built from it would reach schemas nobody named, and escaping it would grant a '
+      + 'schema whose name really contains `%` — neither is what a platform schema means.\n'
+      + `       Fix: ${fix}`);
+  }
+  return schema;
+}
+
 /**
  * Every statement that creates this service's account and grants it what it
  * needs, in the order they must run.
@@ -95,26 +150,30 @@ function requireValue(value, name, fix) {
  *   (`DB_USER` of `config/env-templates/<service>.env`)
  * @param {string} options.password the password the account is created with
  * @param {boolean} [options.ciThrowaway] also grant the throwaway namespace
- *   `<schema>\_%`, which only an integration tier builds into
+ *   `<escaped schema>\_%`, which only an integration tier builds into
  * @returns {string[]} the statements, in order
  */
 function databaseAccountSql({ schema, account, password, ciThrowaway = false } = {}) {
-  requireValue(schema, 'schema', 'pass database.schema from config/service/integration-contract.json.');
+  requireGrantableSchema(schema, 'pass database.schema from config/service/integration-contract.json.');
   requireValue(account, 'account', 'pass DB_USER from this service\'s config/env-templates/<service>.env.');
   requireValue(password, 'password', 'pass the password the account is created with; an account created '
     + 'with an empty password is one anybody on the network can use.');
 
   const identity = `'${account}'@'${ACCOUNT_HOST}'`;
+  // Both grants below are built from this one value: the database-name position
+  // is a LIKE pattern in either of them (see the head of this file).
+  const pattern = escapeSchemaPattern(schema);
 
   const statements = [
     `CREATE USER IF NOT EXISTS ${identity} IDENTIFIED BY '${password}';`,
-    `GRANT ALL PRIVILEGES ON \`${schema}\`.* TO ${identity};`
+    `GRANT ALL PRIVILEGES ON \`${pattern}\`.* TO ${identity};`
   ];
 
   if (ciThrowaway === true) {
-    // The backslash escapes `_` so the pattern stays inside this service; see
-    // the head of this file for the neighbour it would otherwise reach.
-    statements.push(`GRANT ALL PRIVILEGES ON \`${schema}\\_%\`.* TO ${identity};`);
+    // `\_%` is the throwaway SUFFIX — the one wildcard meant to be one — added
+    // to the escaped name; see the head of this file for the neighbour an
+    // unescaped name would otherwise reach.
+    statements.push(`GRANT ALL PRIVILEGES ON \`${pattern}\\_%\`.* TO ${identity};`);
   }
 
   // Last, always: a grant is not live for a connection opened before it.

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/init.sh

@@ -1,8 +1,14 @@
 #!/bin/sh
 set -e
 
+# `npm ci`, not `npm install`: the tree is built from package-lock.json alone,
+# never reconciled against npm's hidden node_modules/.package-lock.json, which
+# a `--package-lock-only` re-pin rewrites while the package directories keep
+# the old versions. A lock that disagrees with package.json stops the boot here
+# instead of installing something nobody declared.
+# @see api/tests/scripts/infra-init-scripts.bats
 oa_npm_install() {
-  npm install --no-audit --no-fund
+  npm ci --no-audit --no-fund
 }
 
 # --- oa-deps-guard v1 (identical in every OA Drive init.sh) ---
@@ -42,7 +48,7 @@ if [ "$CURRENT_HASH" != "$PREVIOUS_HASH" ] || [ "$NEEDS_INSTALL" = "1" ]; then
     echo "$CURRENT_HASH" > "$MARKER_FILE"
     echo "[init.sh] Dependencies installed, marker $MARKER_FILE updated."
   else
-    echo "[init.sh] Dependency install failed - marker $MARKER_FILE left untouched, so the next start retries instead of trusting a half-installed tree. Fix: read the npm error above, then run 'npm install' in this service directory."
+    echo "[init.sh] Dependency install failed - marker $MARKER_FILE left untouched, so the next start retries instead of trusting a half-installed tree. Fix: read the npm error above; a service that has a package-lock.json installs with 'npm ci --no-audit --no-fund' in this directory - 'npm install' is what let the folders and the lock drift apart; a service that has none yet needs 'npm install' once, to create it."
     exit 1
   fi
 else

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)