@onlineapps/conn-orch-validator 10.0.0 → 11.0.0

package/CHANGELOG.md

@@ -4,6 +4,179 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [11.0.0] — 2026-09-17
+
+### Changed — deploy job aplikuje seedy třídy PRODUCTION_LIKE (d.589, W589)
+
+`templates/business-service/.gitlab-ci.yml` (blok `oa-ci v1`): po migracích a před přepnutím se aplikují deklarované
+`database.seeds`, jejichž hlavička nese `Dataset-Class: PRODUCTION_LIKE` (standard `repository-installation-sql-contract.md`
+§4/§5; converter po 10 migracích měl 22 prázdných tabulek). Filtr běží na runneru — box neparsuje JSON ani hlavičky a o třídě
+nerozhoduje; `TEST_ONLY` se nikdy neaplikuje a job to řekne jménem souboru. Seedy se netrackují a jedou při každém nasazení,
+licencí je `-- Idempotency: yes`, její absence i třída mimo slovník odmítnou nasazení před ssh. Devátý poziční argument
+`BIZ_DB_SEEDS`; na boxu `apply_mariadb_seeds_over_tcp <host> <port> <db> <file>...` z běžce neseného z klonu api
+(INFRA `7045a736`), s pojmenovaným odmítnutím mezi předpoklady, když ho klon nenese. Bats `biz-deploy-db-migrations.bats` 24 → 29.
+
+### Fixed — box se resetuje na commit, který runner měřil (d.589b, W589)
+
+Desátý poziční argument `$CI_COMMIT_SHA`; `git merge-base --is-ancestor` + `git reset --hard "$COMMIT_SHA"` místo
+`origin/production` — push během běhu jobu dosud rozešel to, co runner četl v kontraktu, s tím, co box nasadil.
+
+### Fixed — existence `../shared.env` a `config/env-active/<svc>.env` se ověřuje pro každou službu (d.589c, W589)
+
+Dosud jen ve větvi s migracemi; služba bez databáze (pdfgen, hello) se o chybějícím souboru dozvěděla až od
+`docker compose`. Kontrola je před větvením s `Fix:` na runbook, který ty dva soubory zakládá
+(`docs/operations/production-box-provisioning.md` § 3).
+
+
+### Added — řádek uniformy `R-USER` (check `process-identity`) (d.588c, W588)
+
+Produkční stage `Dockerfile` deklaruje `USER node` a uzel služby v `docker-compose.yml` pinuje `user: "1000:1000"`. Druhý
+platformní fakt vyjmutý ze třídy `own` (prvním je node major, `R-NODE`); běžec drží `F-RUNNER`, produkční compose `G-PROD`
+(kontrolní případy, že `R-USER` mlčí, kde hlásí ten druhý). Zčervená u všech osmi služeb — vždy jedním nálezem o `Dockerfile`
+(dev compose už `user:` má 8/8). `doc` = `docs/biz/00-model/service-shape.md` (vzor `R-PORTS-DEV`); sekce „Process identity"
+v README šablony, generovaná oblast řádků přegenerována.
+
+### Fixed — krok, který spadl výjimkou, nechá svůj záznam; nález nese krok (d.602, W602)
+
+Wrapper 9.0.x rozhoduje o opakování padlé FÁZE 0.2 podle `result.steps.<krok>.valid`; krok, jehož tělo vyhodilo výjimku, ale
+záznam nezanechal, došel k wrapperu jako „validator spadl" = přechodně, a koupil si šest pokusů (18,5 min bootu, který uspět
+nemůže). `runStep()` je síť pod všemi sedmi kroky: zapíše `{ valid: false, success: false, threw: true, errors: […] }` s tím,
+co krok naměřil, a nález `{ type: 'STEP_THREW', step, message }`; objektové nálezy kroku 1 nesou v `result.errors` `step`
+(kopie). Věty kroků 2–7 zůstávají větami — `describeValidationFinding()` vydaného wrapperu vykreslí objekt jen s `type` i
+`message`; sjednocení na objekty čeká na wrapper, který `errors[].step` čte (pak 11.0.0). `attributeToStep()` odmítne nálezy,
+které nejsou pole, hláškou §5. Krok 5 hlásí `success`, ostatní `valid` — dvě pole pro jeden pojem, zapsáno jako nález.
+
+
+### Changed — BREAKING: šablona biz služby — produkce běží jako uid 1000, běžec má vlastní `conn-runtime` (d.588, W588)
+
+`templates/business-service/Dockerfile`: obě stage deklarují `USER node` (uid 1000/gid 1000 v `node:24-alpine`) a zakládají
+`/app/logs` + `/app/conn-runtime` pod tím účtem (`COPY --chown=node:node`). Produkční obraz dosud běžel jako root (změřeno
+`docker run --rm <obraz> id` → `uid=0`), zatímco dev kontejner jako 1000:1000 — asymetrie, kterou nikdo nedeklaroval.
+`docker-compose.production.yml`: `user: "1000:1000"` shodně s dev → řádek `G-PROD` u každé služby zčervená do
+`oa-sync-template docker-compose.production.yml`. Blok `oa-test-runner v1` v `docker-compose.yml` dostal anonymní svazek
+`/app/conn-runtime`, aby proof běžce nepřepisoval proof služby (změřeno converterem: běžec nad `.:/app` zapsal
+`validation-proof.json` běžící instance) → řádek `F-RUNNER` zčervená do `oa-sync-template docker-compose.yml`. Nové sady
+`templateProcessIdentity`, `templateRunnerRuntime`, `templateImageIdentity.integration` (skutečný `docker build` + `docker run`;
+bez démona/checkoutu/registry NOT RUN s důvodem, nikdy červená za síť).
+
+### Changed — BREAKING: šablona neměří uniformu při buildu obrazu — verdikt patří CI (d.588b, W588)
+
+Řádek `RUN … oa-validate.js .` ve stage `production` (d.215b, `4b5ed9e6`) měřil uniformu nad build kontextem bez `.git`,
+compose a README — u každé reálné služby (`.dockerignore` je správně vyřazuje) `NOT DEPLOYABLE — 10 finding(s)`, všechny
+„absent", a build spadl. Konfirmace 006/2 („information, never a gate"), 010 (`validate-uniform` z každého commitu nad
+checkoutem) a 011 (strom bez git checkoutu = NOT RUN) větu 001 §3.1 překonaly; řádek je pryč i s testem `add-service.bats`
+54, který teď tvrdí opak. `templateImageIdentity` už nepotřebuje srovnat scaffold pinovanou verzí (19 s místo 46 s).
+
+### Fixed — fixtury uniformy dosynchronizovány na SSOT sdílené sady (dovětek d.533, W588)
+
+14 fixtur `shared.env` a 3 `shared-env.json` se od `f61501cc` lišily jedním klíčem (`JWT_SECRET` `why`/`consumers`);
+`manifestServiceConfig` (`G-SHARED-ENV`) byla proto v HEAD červená. Záměrně rozejitá `service-workspace/api_biz/beta`
+zůstala (vstup případu „not the platform manifest rendered").
+
+### Changed — BREAKING: krok 7 mimo git checkout je NOT RUN, ne „NOT DEPLOYABLE" (d.592, W592)
+
+Produkční obraz není checkout a nenese compose ani README, takže uniforma měřená tam hlásila 12 nálezů nepřítomnosti a
+služba se registrovala `deployable: false` (BIZ-pdfgen 2026-09-16). Verdikt z toho není přísnost, ale špatná odpověď:
+krok vypíše jednu větu NOT RUN s odkazem na CI job `validate-uniform`, `results.deployable` zůstává `null` (= neměřeno,
+jiné tvrzení než `false`), banner ani `ci/deployability.json` nevznikají (konfirmace `biz-service-manifest` 010, 011).
+Sonda `git ls-files` má jedno místo `src/manifest/gitCheckout.js` (`gitCommand`, `listTrackedFiles`, `isGitCheckout`,
+věta `NOT_A_CHECKOUT`); `X-IGNORED` ji bere odtud. Fixtury kroku 7 jsou nově checkouty přes `makeGitCheckout`.
+
+### Added — Tier-1 běžec předává výstup kroku dalším krokům (d.590, W590)
+
+`{{steps.<step_id>.output.…}}` v `input` kroku se rozřeší proti tomu, co dřívější kroky téhož receptu vrátily, takže recept
+si fixturu vytvoří, použije a smaže (vlastník: konfirmace `converter-boot-cookbook` 001 — „opravit v knihovně"). Syntaxe
+i průchod zůstávají cookbook formátu a `@onlineapps/cookbook-core` (`resolveReferencesWith`, `resolveReferencePath` —
+táž kolej jako `WorkflowOrchestrator`); běžec přidává jen scope běhu (`src/utils/stepReferences.js`) tvaru `format.md`
+§ Runtime context (`context.steps`): definice kroku + `output` + `_execution`, adresováno `step_id`. Expanduje se jen
+`input`; `output` se zapisuje jen u kroku, který prošel; scope je per cookbook. `CookbookTestRunner.executeStep()` má
+pátý parametr (kontext běhu; samostatný krok dostane prázdný). Po spadlém kroku s `expect` se další kroky nepouští
+(dnešní chování, nově připnuté testem). NOVÁ ZÁVISLOST: `@onlineapps/cookbook-core` (SSOT) — do `dependencies` před vydáním.
+
+### Added — Tier-1 běžec odmítá recept, který produkce nepřijme (d.598, W598)
+
+Před během: volání template helperu v `input` (`jméno(...)` — Tier-1 registr helperů nemá a `cookbook-template-helpers`
+táhne `content-resolver`, tedy I/O), `{{steps.<id>}}` na krok, který recept nedefinuje (včetně tečkového `{{steps.0}}`;
+gateway odpovídá 400, konfirmace `cookbook-validation-placement` 001 = throw u příjemce jako pojistka), a `depends_on` na
+nedefinovaný krok. Dosud obojí tiše propadlo jako literál. `utils/stepReferences.checkStepInputExpressions()` používá týž
+`resolveReferencesWith()`. Literálem zůstává, co jím podle normy být má (`{{steps[0]}}`, `{{api_input.…}}`, `{{context.…}}`,
+`{{current.…}}`, odkaz na definovaný, ale neběžící/selhavší krok). Dopad na dnešní recepty služeb: 0 ze 43.
+
+### Fixed — `MISSING_COOKBOOKS` nese `Fix:` právě jednou (d.599, W598)
+
+Jediný ze 17 nálezů `ServiceStructureValidator` měl nápravu i uvnitř `message`; wrapper 9.0.1 složením `message (Fix: fix)`
+ji tiskl dvakrát.
+
+### Added — `oa-validate --env-reads [<serviceRoot>]` (d.533c, W533c)
+
+Vypíše jména proměnných prostředí, která služba čte: po řádcích, seřazená, bez duplicit, nic jiného (žádný banner, žádný
+verdikt, žádné `ci/deployability.json`), exit 0; bez čitelného `config/service/integration-contract.json` exit 2 a
+`[oa-validate] … Fix: …` na stderr; nekombinuje se s `--json`, `--library`, `--all`, `--workspace`. Odpovídá bráně nasazení
+`api/scripts/validate-env.sh`, která u biz cíle shazovala nasazení na `JWT_SECRET=CHANGE_ME` — klíč, který žádný biz obraz
+nečte (dohoda s INFRA 2026-09-17). `utils/envContract.js` vystavuje `collectDeclaredEnvNames({serviceRoot, contract})` —
+množina, proti které měří řádek `C-ENV-READS` (`env` blok ∪ `${VAR}` z `config/service/*.json` ∪ endpointové proměnné
+vyžadovaných konektorů), vytažená z `verifyEnvCompleteness`, aby druhý konzument nezaložil druhou definici.
+
+
+### Documentation — zabalený `shared.env` nese komentář u `JWT_SECRET` podle SSOT (d.533)
+
+Šablona `templates/business-service/config/env-templates/shared.env` je render SSOT `api/config/shared-env.json`; `why` u `JWT_SECRET`
+teď jmenuje čtyři infra čtenáře a říká, že business řetězec klíč nese a nečte (`@onlineapps/service-common` bere tajemství jako vstup).
+Vydání 10.0.0 (22:32) přistálo o čtyři minuty dřív než `f61501cc` — zabalená kopie je o tento komentář pozadu, chování beze změny.
+
+### Added — CI pod účtem služby (d.567)
+
+Nový příkaz `oa-biz-ci-gate setup-db-account`: založí účet, který služba **deklaruje** (`DB_USER`
+v `config/env-templates/<služba>.env` — týž klíč, který měří řádek `D-DB-ACCOUNT`), a udělí mu granty na
+jeho schéma. Je to **jediný** krok biz pipeline pod rootem databáze a poslední takový: všechno za ním
+se připojuje jako služba, stejně jako produkce. Důvod je konfirmace `db-migrations-first-deploy` 001
+(„migrace nikdy pod rootem"): sedm pipeline dnes aplikuje tutéž migrační sadu pod `DB_USER: "root"`,
+takže CI dokazuje průchod migrací právy, která produkce neuděluje.
+
+Věty SQL mají **jednu definici** — `src/utils/dbAccountGrants.js`. Produkční runbook a CI jsou dva
+volající, ne dvě kopie (`db-migrations-first-deploy` 001: „žádný nový generátor SQL, žádná druhá kolej").
+Jediný rozdíl CI proti produkci je grant na zahazovací jmenný prostor `` `<schéma>\_%` `` (staví do něj
+integrační tier, `throwawaySchema.js`); `_` je escapované, takže grant zůstává uvnitř jedné služby —
+neescapovaný je `_` zástupný znak LIKE a `oagen_meta_%` by sáhlo i na `oagen_metadata`.
+`GRANT … ON information_schema.*` v sadě **není**: server ho odmítá i rootu (změřeno na dev
+`gen_mariadb10.5`, MariaDB 10.5.17, `ERROR 1044`), a každý účet ten katalog čte filtrovaně sám.
+
+Rootové přihlášení má vlastní jména `CI_DB_ROOT_USER` / `CI_DB_ROOT_PASSWORD` a nebere se z `DB_USER`
+(`architecture-principles.md` §8) — právě to, že ty dvě identity byly jedna hodnota, příkaz končí.
+Heslo účtu je zahazovací hodnota jobu (`DB_PASSWORD`), nikdy `CHANGE_ME` ze šablony: šablona deklaruje
+klíč, ne tajemství. Služba bez bloku `database` hlásí `NOT APPLICABLE` a končí nulou, jako `setup-db`.
+Žádné heslo se na výstup nedostane ani na cestě selhání.
+
+Že ty granty **stačí** — a pořád nejsou příliš — není vlastnost textu SQL, ale odpovědi serveru, takže je
+to změřeno proti skutečné MariaDB (dev `gen_mariadb10.5`, 10.5.17): se samotným produkčním grantem server
+stavbu zahazovacího schématu odmítne (`ERROR 1044`), po `setup-db-account` projde, a účet přitom pořád
+nedosáhne na sousední službu — ani na její schéma, ani na zahazovací schéma v jejím jmenném prostoru, ani
+na řádky, ani na její jméno v katalogu. Soused se jmenuje `<ns>ax` k `<ns>a` právě proto, že neescapované
+`_` by ho pustilo dovnitř.
+
+Kaskáda: sedm repozitářů s databází přepíše v jobu `test` `DB_USER: "root"` na účet služby a zařadí
+`setup-db-account` před `ci:gate:setup`.
+
+### Added — řádek uniformy `D-DB-CI-ACCOUNT` (d.567)
+
+`D-DB-ACCOUNT` měří deklaraci (`DB_USER` v šabloně prostředí); nic neměřilo prostředí, ve kterém se ta
+migrační sada každý den skutečně aplikuje. Nový řádek (`severity: deploy`, vlastník BIZ-general) hlásí
+`DB_USER` s hodnotou `root` a `ci:gate:setup`, před kterým neběží `setup-db-account`. Samostatný řádek,
+ne rozšíření `D-DB-ACCOUNT`: jiný soubor, jiná oprava, a jeden řádek se dvěma opravami jsou dva
+mechanismy pod jedním jménem (`automation-gates.md` §1.2). Čte řádky **mimo** blok `oa-ci v1` (ten je
+G-CI), takže nekřísí problém, kvůli kterému byl celosouborový řádek nad `.gitlab-ci.yml` po třech dnech
+stažen.
+
+Měří, KDO kroky nad databází pouští, a záměrně ne, ZDA je repozitář pouští: job, který nestaví schéma,
+nemá účet, který by tento krok zakládal. Hranice je napsaná, protože nevyslovená hranice se čte jako
+pokrytí (`automation-gates.md` §5). Obě pravopisné podoby téhož: `DB_USER: "root"` v `variables:` i
+`DB_USER=root` jako předřazené přiřazení na samotném kroku (změřený tvar `api_biz/hello-service`).
+Komentář, který jmenuje `ci:gate:setup`, krokem není (změřený tvar `api_biz/meta`).
+
+Změřeno nad všemi osmi repozitáři: sedm hlásí dva nálezy s číslem řádku a proveditelnou opravou,
+`pdfgen` (bez bloku `database`) mlčí z konstrukce. Zrcadla generovaného seznamu řádků (README uniforma
+šablony i všech fixtur, `api/templates/business-service/README.md`) přegenerována v témže commitu.
+
 ## [10.0.0] — 2026-09-16
 
 ### Removed — `MockStorage` (d.583)

package/README.md

@@ -68,6 +68,44 @@ signal saved to `ci/deployability.json`
 > The list said "Service Readiness — HTTP API works" until 2026-08-27. That step
 > was removed on 2026-08-22 under ADR 0005 and this README kept describing it.
 
+### The shape of a run's result
+
+```js
+{
+  success, steps: { structure, config, env, operations, cookbooks, connectors, manifest },
+  errors: [ … ], warnings: [ … ],
+  totalTests, passedTests, failedTests,
+  deployable, deployFindings, notRun, durationMs, proof?, fingerprint?
+}
+```
+
+**Every step that was reached has a record in `steps`, and a step that THREW has one
+too** — `{ valid: false, threw: true, errors: [ … ] }`, with whatever it had already
+measured kept beside it. Absence therefore means one thing only: the run stopped before
+that step (it fail-fasts after steps 1 and 3). That distinction is not cosmetic:
+`@onlineapps/service-wrapper` 9.0.x decides whether a failed FÁZE 0.2 may be retried by
+reading `steps.<step>.valid` — `structure`, `config`, `env`, `operations` and `manifest`
+read files alone, so their verdict is permanent, while `cookbooks` and an exception of the
+validator itself keep the retry budget. Until d.602 a step whose body threw left NO record,
+so a structural defect read as "the validator threw" and bought the full six attempts:
+18,5 minutes of a boot that cannot succeed (measured on biz-converter, W591).
+
+**`errors` is one flat array of two shapes**, and a reader must handle both:
+
+| Shape | Written by | Carries `step` |
+|---|---|---|
+| object `{ type, path?, message, fix?, step }` | step 1, and every step that THREW (`type: 'STEP_THREW'`) | yes |
+| sentence, already in the `[Context] Problem - Expected/Fix` shape | steps 2-7 by their rules | no — see below |
+
+The `step` marker is ADDED to the objects, never substituted for what they carried, and the
+sentences keep their shape. That asymmetry is deliberate and measured: the released
+wrapper's `describeValidationFinding()` renders a string verbatim and an object only when
+it carries `type` **and** `message`, so rewriting the sentences into `{ step, message }`
+objects would deliver them to the operator as raw JSON. Unifying on objects is therefore a
+BREAKING change that waits for a wrapper which reads `step` (reported to BIZ-general with
+d.602). A finding's own `errors` array inside `steps.<step>` is the step's answer and is
+left untouched — the marker is on the copy that travels in `errors`.
+
 ---
 
 ## Pre-validation runs in-process — and against the real database
@@ -99,6 +137,140 @@ failure.
 
 ---
 
+## A recipe builds its own fixture — `{{steps.<step_id>.output.…}}`
+
+A step's `input` may reference what an EARLIER step of the same cookbook
+returned. The runner resolves those references before it calls the handler, so a
+recipe can create the data it needs, use it, and delete it again — instead of
+depending on a seed that exists in one environment and not in another.
+
+```json
+{
+  "steps": [
+    { "step_id": "create_fixture", "service": "biz-x", "operation": "create-row",
+      "input": { "label": "boot-fixture" } },
+    { "step_id": "use_fixture", "service": "biz-x", "operation": "convert",
+      "depends_on": ["create_fixture"],
+      "input": { "id": "{{steps.create_fixture.output.id}}" } },
+    { "step_id": "delete_fixture", "service": "biz-x", "operation": "delete-row",
+      "depends_on": ["create_fixture"],
+      "input": { "id": "{{steps.create_fixture.output.id}}" } }
+  ]
+}
+```
+
+**The syntax is not this package's.** Which forms exist, that a whole-value
+expression keeps the resolved type while an expression inside text is
+stringified, that a step is addressed by `step_id` and never by position, and
+that an unresolvable reference survives as literal text — all of it is owned by
+[`api/docs/biz/40-cookbooks/variable-references.md`](../../../docs/biz/40-cookbooks/variable-references.md),
+and the traversal is `@onlineapps/cookbook-core`
+(`resolveReferencesWith` + `resolveReferencePath`) — the same two functions
+`WorkflowOrchestrator` calls. There is no second parser here, which is what keeps
+a recipe behaving the same at boot and in a production workflow.
+
+What Tier-1 adds is the SCOPE, and only the scope
+(`src/utils/stepReferences.js`):
+
+- `input` is the only field expanded. `expect`, `service`, `operation` and
+  `depends_on` are read literally — the format names three expansion sites and
+  none of them is `expect`
+  ([variable-references.md](../../../docs/biz/40-cookbooks/variable-references.md)
+  § Limitations).
+- A step entry is spelled the way
+  [`format.md`](../../../docs/biz/40-cookbooks/format.md) § Runtime context
+  (`context.steps`)
+  spells it: the step definition plus `output` and `_execution`, addressed by
+  `step_id`.
+- `output` appears on a step that PASSED. A failed step is recorded with its
+  status alone, so a reference into it stays literal and the failing input shows
+  the reader which step did not deliver.
+- The scope is per COOKBOOK. A run over a directory gives every cookbook its own,
+  so two recipes may use the same step names.
+- A Tier-1 run has no workflow input and no delivery, so `{{api_input.…}}`,
+  `{{delivery.…}}` and `{{current.…}}` resolve to nothing and stay literal.
+
+### What the runner REFUSES, because production does too
+
+A literal `{{…}}` is the right outcome for a value that is missing at that
+moment — a step that has not run yet, or one that failed. It is the wrong
+outcome for an expression no run could ever resolve, because then a green Tier-1
+certifies a recipe production does not accept. Two such shapes are refused
+BEFORE any step of the cookbook runs, each with its own `Fix:`:
+
+| Written in a step's `input` | Tier-1 | Production |
+|---|---|---|
+| `{{webalizeString(…)}}`, `{{string2file(…)}}` — any `name(…)` | refused: `Step <id> input calls the template helper "<name>"` | the orchestrator evaluates it through its helper registry, and throws on a name that registry does not carry |
+| `{{steps.<id>.…}}` naming no step THIS cookbook defines (`{{steps.0.…}}` included — `0` is a name no recipe declares) | refused: `Step <id> references an undefined step` | 400 `Invalid cookbook references` at submission |
+| `depends_on` naming no step this cookbook defines | refused: `Step <id> depends on an undefined step` | — |
+
+The helper registry is absent from the runner on purpose: a helper reaches its
+own runtime (`@onlineapps/content-resolver`, files, storage), which is not what a
+startup probe may do. A recipe that needs a computed value builds it in an
+earlier step and references that step's output.
+
+The reference half is the receiver's side of the owner's 2026-09-02 decision
+([`cookbook-validation-placement.md`](../../../docs/governance/confirmations/cookbook-validation-placement.md)
+001): the gateway answers 400 at submission, and the paths that bypass the
+gateway — a boot run is one — refuse it themselves. What stays literal is
+unchanged: `{{steps[0].…}}` (the bracket form is not a step reference),
+`{{api_input.…}}`, `{{context.…}}`, `{{current.…}}`, and a reference into a
+step that is defined but has not produced anything yet.
+
+Why the runner gained this: biz-converter's boot recipe needed a row that only a
+TEST_ONLY seed supplies, so on production Tier-1 answered `NOT_CONVERTIBLE` and
+the container restarted in a loop. The owner's decision was that the recipe stays
+as written and the runner learns what the orchestrator already does —
+`api/docs/governance/confirmations/converter-boot-cookbook.md` 001.
+
+---
+
+## The CI database account is the service's own (`setup-db-account`)
+
+`db-migrations-first-deploy` 001 says it in one line: **migrace nikdy pod
+rootem.** Production applies a service's migration set as `oagen_<service>`, an
+account granted its own schemas and nothing else. Until d.567 seven biz
+pipelines applied the SAME set under `DB_USER: "root"`, so CI proved the
+migrations under rights no production box grants.
+
+`setup-db-account` closes that gap. It runs **first** in `before_script` and is
+the **only** step of the pipeline that uses the database root account:
+
+```yaml
+  before_script:
+    - npx oa-biz-ci-gate setup-db-account   # the one root step
+    - npm run ci:gate:setup                 # …and everything after it is the service
+```
+
+Three facts, three owners, none of them invented by the command:
+
+| Fact | Owner |
+|---|---|
+| the schema | `database.schema` of `config/service/integration-contract.json` — what `setup-db` builds |
+| the account | `DB_USER` of `config/env-templates/<service>.env` — the declaration uniform row `D-DB-ACCOUNT` measures |
+| the statements | `src/utils/dbAccountGrants.js` — the same definition the production runbook installs from |
+
+The job supplies the credentials, and the two identities are named **separately**
+(`architecture-principles.md` §8 — the whole point is that they stop being one
+value):
+
+| Variable | What it is |
+|---|---|
+| `CI_DB_ROOT_USER` / `CI_DB_ROOT_PASSWORD` | the administrative account of the database sidecar, used by this step alone |
+| `DB_USER` | the account every later step connects as; it must equal what the env template declares, and the command refuses the job otherwise |
+| `DB_PASSWORD` | the throwaway password the account is **created with** and connects with — an env template declares the key, never the secret |
+
+A service whose contract declares no `database` block reports `NOT APPLICABLE`
+and exits 0, the way `setup-db` does. Neither password is ever printed, on any
+path.
+
+**CI gets one grant production does not**: `` `<schema>\_%` ``, the throwaway
+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`.
+
+---
+
 ## Environment contract (`env` block)
 
 One declaration in `config/service/integration-contract.json`, two consumers:
@@ -349,6 +521,18 @@ a stateless service is silent — `pdfgen` is the measured case.
   (confirmation `db-accounts-per-service` 001: root stops being an operational identity —
   it was the identity of nine containers across eight repositories). A repository that
   declares a database and no `DB_USER` is a finding and not a silence.
+* **`D-DB-CI-ACCOUNT`** — the row above measures the DECLARATION; this one measures the
+  one environment where that migration set is applied every day. Measured 2026-09-16:
+  seven of eight biz pipelines set `DB_USER: "root"` in their `test` job while declaring
+  `oagen_<service>` in the template, so CI proved the set under rights no production box
+  grants — the gap `db-migrations-first-deploy` 001 names ("migrace nikdy pod rootem") in
+  the only place a migration can be tried before a deploy. It reports that value, and a
+  `ci:gate:setup` with no `setup-db-account` step before it. A SEPARATE row rather than a
+  wider `D-DB-ACCOUNT`: another file, another fix, and one row with two fixes is two
+  mechanisms under one name (`automation-gates.md` §1.2). It reads the lines OUTSIDE the
+  `oa-ci v1` block, which is `G-CI`'s, and it asks WHO the database steps run as —
+  deliberately not WHETHER a repository runs them, since a job that builds no schema has
+  no account for the step to create.
 
 One more row about the database sits outside this section on purpose. **`X-DB-CONFIG`**
 is in `files.forbidden`, beside `X-HOOKS` and `X-PREVAL`, and it forbids one path:
@@ -552,9 +736,9 @@ severity means it never stops one.
 ### Step 7 and the deployability signal
 
 The same check is step **7/7** of the boot validation (`ValidationOrchestrator`), so a
-service measures itself at every start against the manifest its pin selected. The two
-blocking severities have different consequences, and that difference is the point
-(confirmation `biz-service-manifest` 001 §4):
+service started from a git checkout measures itself at every start against the manifest
+its pin selected. The two blocking severities have different consequences, and that
+difference is the point (confirmation `biz-service-manifest` 001 §4):
 
 | Severity | Boot | `results` | What the operator sees |
 |---|---|---|---|
@@ -590,8 +774,34 @@ belongs to the uniform (`verdict.incomplete` in the manifest, with `{count}` and
 in it), never to the renderer: a library says `publish row(s)` there, and
 `PUBLISHABLE — no findings` where nothing was skipped.
 
-The same verdict is written, in the same step, to **`ci/deployability.json`** of the
-service root, which `deploy-production` reads and refuses on a single row. The `oa-validate`
+#### Outside a git checkout the step does not measure (d.592)
+
+A production image is not a checkout and carries neither `docker-compose.yml` nor
+`README.md`, so the uniform measured THERE reports absences that say nothing about the
+repository — 12 findings for a healthy service. Owner decision 2026-09-17 (confirmation
+`biz-service-manifest` 011): the step then reports NOT RUN, in one line, and measures
+nothing:
+
+```
+[ValidationOrchestrator] NOT RUN  manifest conformance — this tree is not a git checkout
+(git ls-files could not answer), so what a clone would receive cannot be read — a container
+and an exported tarball are in exactly this state. Deployability is proven per commit by
+the CI job `validate-uniform` over the checkout (confirmation biz-service-manifest 010).
+```
+
+`results.deployable` is then `null`, which is NOT MEASURED — a different statement from
+`false`, which is why the field has three states. No banner, no table, and **no
+`ci/deployability.json`**: the file IS a verdict, and this run reached none. The probe is
+the one `X-IGNORED` already used (`src/manifest/gitCheckout.js`), so the row and the step
+cannot answer the same question differently.
+
+What proves deployability is the CI job `validate-uniform`, from every commit, over the
+checkout (confirmation `biz-service-manifest` 010) — the only place that can see what a
+clone receives.
+
+The verdict of a run that DID measure is written, in the same step, to
+**`ci/deployability.json`** of the service root, which `deploy-production` reads and
+refuses on a single row. The `oa-validate`
 CLI writes the same file, through the same builder and writer
 (`src/manifest/deployabilitySignal.js`), for the service run it just printed — one file
 shape with two producers, never two shapes:
@@ -610,10 +820,10 @@ shape with two producers, never two shapes:
 ```
 
 **Two claims, not one.** `deployable` says nothing blocked among the rows that RAN;
-`complete` says no row that CAN block this bearer was skipped. Inside a service container
-the rows reading the workspace cannot run at all, so a signal is routinely deployable and
-incomplete at once — and a gate reading only the first was honouring a `--skip` nobody had
-flagged (`automation-gates.md` §1.5). **The deploy gate takes a signal only when both are
+`complete` says no row that CAN block this bearer was skipped. A run from a checkout that
+cannot reach the workspace root (the `--workspace` that names it) answers the workspace
+rows NOT RUN, so its signal is deployable and incomplete at once — and a gate reading only
+the first was honouring a `--skip` nobody had flagged (`automation-gates.md` §1.5). **The deploy gate takes a signal only when both are
 true**; the complete run is produced from the api checkout with
 `npx oa-validate --workspace <root> <service root>`, and since d.232 that run writes the
 file it is asked for. A service root OUTSIDE the workspace root cannot produce a complete
@@ -630,7 +840,8 @@ rows that could not look are not passes, and each entry carries the `severity` o
 that did not run — which is what decides `complete`.
 
 There is no switch that skips the step and none that moves the file — one path,
-unbypassable.
+unbypassable. What decides whether the step measures is not a flag anybody sets but
+whether git can answer in the tree it was handed (above).
 
 ### Two run modes, three scopes
 
@@ -700,6 +911,39 @@ looked and found nothing", so each row that needs the workspace — `workspace`
 alike — is reported `NOT RUN — service root is outside the workspace root <root>` instead,
 in the banner and in the signal alike.
 
+### Which names the image reads (`oa-validate --env-reads`)
+
+A third mode, and not a verdict at all: it answers ONE question — which environment
+names this service reads — for a deploy gate that must not judge a service's `.env`
+against the platform's whole key set.
+
+```bash
+mapfile -t reads < <(npx oa-validate --env-reads "$repo") || exit 1
+for key in "${reads[@]}"; do
+  grep -q "^${key}=" "$env_file" || fail "$key is declared and missing"
+done
+```
+
+Names on stdout, one per line, sorted, without duplicates, and nothing else: no
+banner, no table, no `ci/deployability.json`. Exit 0 with the list, exit 2 with an
+`[oa-validate] … Fix: …` line on stderr where there is no readable
+`config/service/integration-contract.json` — a gate that cannot get the set must
+stop, never continue with an empty one. The mode combines with no other option
+(`--json`, `--library`, `--all`, `--workspace` are refused), because every other
+mode prints a verdict into the same stdout.
+
+The set is the one row `C-ENV-READS` measures the repository against — the contract's
+`env` block, the `${VAR}` placeholders of `config/service/*.json`, and the endpoint
+variables of the connectors the contract declares required — so the gate and the
+uniform cannot disagree about what a service reads. It is deliberately NOT a grep for
+`process.env`: most of the platform's environment is read inside installed libraries,
+where a grep over `src/` sees nothing, and in a gate a set too small means a key
+silently unchecked.
+
+The other direction is deliberate too: a name the SOURCE reads that the contract does
+not declare is absent here. That is a blocking finding of `C-ENV-READS`, with its own
+fix — and a gate must not demand a value for a key nobody owns.
+
 ### Uniforma knihoven (`oa-validate --library`)
 
 `manifests/library.manifest.json` is the same concept for the shared libraries, in the

package/docs/DESIGN.md

@@ -65,7 +65,15 @@ unit test in d.583 (`tests/unit/mockInfrastructureRetired.test.js`).
 - `ValidationProofGenerator` — fingerprint + codec helpers
 - `CookbookTestRunner` — cookbook execution probe. The single rail: the second
   one, `WorkflowTestRunner`, was deleted on 2026-09-05 (no consumer anywhere in
-  the workspace, and it read the banned `step.id`)
+  the workspace, and it read the banned `step.id`). A step's `input` may
+  reference an earlier step's output, so a recipe can build, use and remove its
+  own fixture instead of depending on a seed one environment has and another does
+  not (owner: `../../../docs/governance/confirmations/converter-boot-cookbook.md`
+  001). The syntax belongs to the cookbook format
+  ([variable-references.md](../../../docs/biz/40-cookbooks/variable-references.md))
+  and the traversal to `@onlineapps/cookbook-core`, the same rail
+  `WorkflowOrchestrator` runs on; `src/utils/stepReferences.js` supplies only the
+  run scope, and README § "A recipe builds its own fixture" says what it holds
 - `CookbookTestUtils` — static cookbook-structure validators
 
 ### Test Suite Helpers
@@ -93,7 +101,8 @@ unit test in d.583 (`tests/unit/mockInfrastructureRetired.test.js`).
 
 1. **Service contract** — structure, config files and the v3 operations rules
 2. **Environment contract** — every name declared `env.required` is set
-3. **Workflow capability** — can process cookbooks, in-process, with mocks
+3. **Workflow capability** — can process cookbooks, in-process, including a
+   recipe whose later steps read what its earlier steps returned
 4. **Connector contract** — the two declarations agree and the environment backs them
 
 ## What We DO NOT Test

package/manifests/biz-service.manifest.json

@@ -108,7 +108,7 @@
     ],
     "own": {
       "concern": "the files of the template whose CONTENT the service decides, and the reason each is not held to the platform's copy",
-      "why": "a file added to the template is a decision about who guards it, and this class is the decision written down: no row holds these to the template, because their content IS the service. Dockerfile is the exception that proves the rule - its one platform fact, the node major, is R-NODE's row, and everything else in it is this service's build. docs/README.md is the same decision for the map of the documentation tree: which branches a service has is the service's, and what the platform holds the tree to is not that prose but D-LINT, which asks the documentation lint whether the tree is clean. It is the map alone, not docs/ - the three installation documents under docs/80-setup/ ARE held to a skeleton, and a class covering them would exempt what a row requires. The class exists so that the completeness check of finding 18 has an answer other than silence for every file the template carries (automation-gates.md \u00a75)",
+      "why": "a file added to the template is a decision about who guards it, and this class is the decision written down: no row holds these to the template, because their content IS the service. Dockerfile is the exception that proves the rule - its TWO platform facts are rows of their own, and everything else in it is this service's build: the node major is R-NODE's row, and WHICH USER the process runs as is R-USER's (added d.588c, after a production image built from the template was measured running as uid 0 while the dev container beside it ran as 1000). What a service BUILDS is its own; what it RUNS AS is the platform's. docs/README.md is the same decision for the map of the documentation tree: which branches a service has is the service's, and what the platform holds the tree to is not that prose but D-LINT, which asks the documentation lint whether the tree is clean. It is the map alone, not docs/ - the three installation documents under docs/80-setup/ ARE held to a skeleton, and a class covering them would exempt what a row requires. The class exists so that the completeness check of finding 18 has an answer other than silence for every file the template carries (automation-gates.md \u00a75)",
       "allowed": [
         "Dockerfile",
         "index.js",
@@ -497,6 +497,20 @@
         "fix": "in docker-compose.yml set the service block's command to [\"node\", \"index.js\"] (the entrypoint init.sh execs it, so node becomes PID 1), then recreate the container and smoke it",
         "doc": "api/docs/governance/confirmations/biz-compose-pid1.md"
       },
+      {
+        "id": "R-USER",
+        "check": "process-identity",
+        "image_path": "Dockerfile",
+        "image_stage": "production",
+        "path": "docker-compose.yml",
+        "service_user": "node",
+        "service_uid": "1000:1000",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "WHICH USER the process is, which is a platform fact and not a service build. Measured 2026-09-17 on a production image built from the platform template: `docker run --rm <image> id` answered uid=0(root) gid=0(root), while the dev container beside it ran as 1000:1000 because docker-compose.yml pins it - nobody had decided that difference, the production stage simply declared no USER, and nothing in the uniform could say so because Dockerfile is a file of the own class. This row is the SECOND platform fact carved out of that class, for the same reason as the first (R-NODE, the node major): what a service BUILDS is its own, what it RUNS AS is the platform. It measures the two places nothing else holds - the production stage of the Dockerfile, which is the stage CI builds and the one the defect lived in, and the SERVICE node of the dev compose. The runner user: sits inside the block F-RUNNER holds byte for byte, and the production compose is the whole-file render of G-PROD, so neither is repeated here (change-discipline.md, One rail per concern). The two spellings are ONE identity, and the row carries both because no machine resolves an account name to a uid without the image: node is uid 1000, gid 1000 in the node images this platform builds on, measured docker run --rm node:24-alpine id node",
+        "fix": "in the production stage of Dockerfile put RUN mkdir -p /app/logs /app/conn-runtime && chown -R node:node /app, then USER node before npm ci, and --chown=node:node on both COPY lines; in docker-compose.yml give the service node the line user: \"1000:1000\"",
+        "doc": "api/docs/biz/00-model/service-shape.md"
+      },
       {
         "id": "R-PORTS-DEV",
         "check": "compose-no-ports",
@@ -587,6 +601,19 @@
         "fix": "set DB_USER in this service's env template to oagen_<shortname>, where <shortname> is what config/service/config.json declares; the account and its grants are created by the operator installing the schema",
         "doc": "api/docs/governance/confirmations/db-accounts-per-service.md"
       },
+      {
+        "id": "D-DB-CI-ACCOUNT",
+        "check": "db-ci-account",
+        "path": ".gitlab-ci.yml",
+        "block": "oa-ci v1",
+        "key": "DB_USER",
+        "account": "root",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "D-DB-ACCOUNT one row up measures the DECLARATION - the account production installs. Nothing measured the ONE environment where that migration set is applied every day. Measured 2026-09-16 over the eight biz repositories: seven set DB_USER: \"root\" in their test job while declaring oagen_<service> in the env template, so CI proved the set under rights no production box grants - the gap db-migrations-first-deploy 001 names (\"migrace nikdy pod rootem\") in the only place a migration can be tried before a deploy. A separate row and not a wider D-DB-ACCOUNT: another file, another fix, and one row with two fixes is two mechanisms under one name (automation-gates.md §1.2). It reads the lines OUTSIDE the oa-ci v1 block, because that block is the platform's and G-CI compares it byte for byte; reading a region and not the whole file is also what keeps it clear of the defect that had the whole-file row over .gitlab-ci.yml withdrawn after three days. It asks WHO the database steps run as and deliberately not WHETHER a repository runs them: a job that builds no schema has no account for the step to create, and demanding one would be this row inventing a rule (truth-over-agreement.md §6). Silent for a service with no database block by construction - pdfgen is the live case",
+        "fix": "in the test job of .gitlab-ci.yml set DB_USER to the account config/env-templates/<service>.env declares, give DB_PASSWORD a throwaway value of the job, name the sidecar's root credential CI_DB_ROOT_USER / CI_DB_ROOT_PASSWORD, and run `npx oa-biz-ci-gate setup-db-account` as the first before_script step, before ci:gate:setup",
+        "doc": "api/docs/governance/confirmations/db-accounts-per-service.md"
+      },
       {
         "id": "D-DB-HEADERS",
         "check": "install-contract",

package/package.json

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