@onlineapps/conn-orch-validator 12.0.0 → 12.1.1

package/CHANGELOG.md

@@ -4,6 +4,155 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [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)
+
+Řá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)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "12.0.0",
+  "version": "12.1.1",
   "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/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/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/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/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/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

@@ -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