@onlineapps/conn-orch-validator 12.1.1 → 13.0.0

package/CHANGELOG.md

@@ -4,6 +4,613 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [13.0.0] — 2026-09-27
+
+pin: `@onlineapps/cookbook-core` 6.0.0 → 7.0.0
+pin: `@onlineapps/error-handler-core` 3.1.0 → 4.0.0
+pin: `@onlineapps/handler-contract` 1.0.0 (nová závislost)
+pin: `@onlineapps/service-validator-core` 2.1.0 → 2.2.0
+
+### Changed — BREAKING — `CookbookTestUtils.createControlFlowStep` vyrábí krok, který schéma V2.1 přijme (d.1060)
+
+Generátor dřív vracel tvary, které schéma `@onlineapps/cookbook-core` nezná (`items`, `condition`,
+`cases`/`branches` jako pole, `body` jako objekt), `step_id` s pomlčkou a řídicí krok bez `service`
+(`docs/governance/confirmations/cookbook-execution-owner.md` 002).
+
+- `options.service` je povinný; krok ho nese a výchozí vnořené tasky běží v téže službě.
+- Tvary podle schématu: `foreach.iterator` + `body` jako pole, `switch.expression` + `cases` jako objekt,
+  `fork_join.branches` jako objekt, nově i typ `steps`; výchozí `step_id` odpovídá `^[a-zA-Z0-9_]+$`.
+- Odmítá se jménem (`[CookbookTestUtils] createControlFlowStep('<typ>') - … Fix: …`): chybějící `service`,
+  volba `id` (dřív alias `step_id`) a typ mimo `foreach`, `switch`, `fork_join`, `steps`
+  (dřív vrátil napůl postavený krok).
+- Testy: `tests/unit/cookbookStepIdentity.test.js` pouští každý vyrobený krok přes `validateCookbook`
+  z `@onlineapps/cookbook-core`; dva staré případy, které tvrdily původní tvar, nahrazeny.
+
+### Added — `oa-validate --library <packageDir> --as-version <X.Y.Z>`: `L-CHANGELOG` soudí verzi, která se vydává (d.1040)
+
+Brána F10 (`scripts/ci/lib/prepublishGate.js`) dostává od `publish-library.sh` `--as-version
+<NOVÁ>` a posouvala jí jen svá pravidla; uniforma (G7) běžela bez verze a `L-CHANGELOG` četl
+`version` z `package.json` — tedy STAROU verzi. Suchý běh tak pustil chybějící `## [NOVÁ]`
+(d.1033: `error-handler-core --as-version 4.0.0` PASS bez hlavičky) a balíček, jehož stará verze
+záznam neměla, odmítl kvůli verzi, kterou nikdo nevydával (d.1038, `handler-contract`).
+
+- CLI: `--as-version <X.Y.Z[-prerelease]>`, jen s `--library <packageDir>`. Bez hodnoty, ve
+  špatném tvaru, s `--all` nebo bez `--library` se odmítá jménem (exit 2, `Fix:`).
+- `runManifest({ …, asVersion })` hodnotu na vstupu ověří (`isTargetVersion`, exportováno — jediný
+  vlastník tvaru, CLI se ptá téhož) a předá ji každé kontrole jako `asVersion`.
+- `library-changelog-entry` soudí `asVersion`, je-li dána, jinak `version` z `package.json` —
+  dvě legitimní otázky (vydání × audit stromu), ne hodnota a její náhrada. Nález říká, kterou
+  soudil: `no entry for the version being published (4.0.0, given by --as-version; package.json
+  says 3.1.0)`. Bez `--as-version` je chování i text beze změny.
+
+Text opravy řádku `L-CHANGELOG` (`manifests/library.manifest.json`) říkal „the version in
+package.json" — při suchém běhu vydání tedy posílal psát záznam pro verzi, ze které se odchází.
+Nově: „the version being published — the one in package.json, or the one --as-version names on a
+publish dry run" (d.1040b).
+
+Zapojení do brány (G7 předá `--as-version`) je mimo tento balíček (`scripts/ci/lib/prepublishGate.js`).
+
+### Changed — BREAKING: Tier-1 `test.timeout`, který není kladné číslo, se odmítá jménem (d.1001)
+
+`_dispatchViaHandler` bral limit kroku jako `testConfig.timeout || this.timeout`. Zapsaná
+`0`, `-1` nebo `NaN` tak tiše propadla na výchozí hodnotu běžce a řetězec `"5"` se dostal
+do `setTimeout` jako řetězec — recept říkal jedno, běh dělal druhé
+(`architecture-principles.md` §3). Nově rozhoduje jedno místo, `_stepTimeout(testConfig)`,
+podle kontraktu `docs/biz/40-cookbooks/testing.md` § The `test` block: klíč chybí → výchozí
+hodnota běžce (volba konstruktoru `timeout`); klíč je a není kladné konečné číslo → krok
+selže dřív, než se handler zavolá (`result.request === null`), s hláškou
+`[CookbookTestRunner] test.timeout must be a positive number of milliseconds - got <hodnota>.
+Expected: … Fix: write a positive number (e.g. "timeout": 5000) in the cookbook's test block,
+or drop the key.` Platná hodnota výchozí přebíjí jako dosud.
+
+BREAKING pro recept, který nesl `0`, záporné číslo, `NaN`, `Infinity` nebo číslo jako
+řetězec: dřív prošel, nově jeho kroky selžou. Změřeno před změnou nad 56 recepty
+(`api/cookbooks`, `api_biz/*/tests/cookbooks` na `origin/devel`): 21 bez bloku `test`,
+zbylé nesou `timeout` 5000, 10000 nebo 15000 — žádný recept se tím nemění.
+
+### Changed — BREAKING: Tier-1 běžec `correlation_id` a `workflow_id` z kroku nečte (d.1001)
+
+Dřív `step.correlation_id || crypto.randomUUID()` a `step.workflow_id || correlationId`.
+Formát kroku (`docs/biz/40-cookbooks/format.md` § Task step, `TaskStep`
+v `cookbook.v2.schema.json`) ani jeden klíč nezná a produkce je z kroku nečte, takže
+identitu běhu vyrábí jen běžec: `correlation_id` = nové `crypto.randomUUID()` pro každý
+krok, `workflow_id` = to samé uuid. Krok, který klíče dál nese, se NEodmítá — `TaskStep`
+drží `additionalProperties: true` záměrně (conf `parked-features` 001) a odmítnutí tady by
+byla druhá kolej proti `@onlineapps/cookbook-core` — klíče se chovají jako každý neznámý
+klíč: nečtou se. BREAKING pro Tier-1: recept, který těmi klíči nastavoval ctx handleru,
+je nově nenastaví. Změřeno: 0 z 56 receptů je na kroku nese.
+
+`step.person_id` se NEMĚNÍ a běžec ho čte dál: zda Tier-1 nese jednající osobu a odkud,
+rozhoduje conf `testing-tenant-identity` 001 (koordinátor).
+
+Doklad: `tests/unit/CookbookTestRunner.stepTimeoutAndIdentity.test.js` (RED 6 z 12 —
+pět odmítnutí timeoutu a uuid místo hodnoty z kroku; kontrolní: chybějící timeout =
+výchozí běžce, platný ho přebíjí, krok bez klíčů beze změny, `person_id` se čte) a
+`…stepTimeoutAndIdentity.integration.test.js` přes `runCookbook()` s reálnými handlery
+fixture (RED 2 z 3, kontrolní recept `two-steps.json` beze změny). Fixture služba má
+novou operaci `sleep`, podle které je vidět, proti kterému limitu handler běžel.
+
+### Fixed — `L-PACK-TESTS` pozná allowlist glob, který pustí `tests/` do tarballu; `tests/` pod `templates/**` výslovně není tier balíčku; kořenový `jest.config.js` z tarballu pryč (d.1002)
+
+- **Glob v `files`:** řádek dřív uznal jen doslovný záznam `tests`. Balíček s `files: ["**/*.js"]`
+  nebo `["*"]` přitom `tests/unit/*.test.js` do tarballu zabalí (změřeno `npm pack --dry-run --json`)
+  a řádek o tom mlčel. Teď záznam, jehož první segment odpovídá `tests` (`tests`, `*`, `**`, …),
+  je nález, který ten záznam jmenuje: `the files allowlist entry "**/*.js" reaches tests — the tier
+  would ship to every consumer`. Změnil se i text nálezu pro doslovné `tests` (dřív `the files
+  allowlist names tests …`). Glob omezený na kořen (`*.js`) adresář nezasáhne a nálezem není.
+- **Šablona:** řádek měří jen `tests/` v kořeni balíčku, tedy jeho vlastní tier. `tests/` pod
+  `templates/**` je obsah šablony, kterou balíček vydává záměrně (`templates/business-service/tests/**`
+  pro `oa-sync-template --new`), a nálezem není. Teď to říkají docblock kontroly i README; testy
+  tvrdí obě strany.
+- **Tarball validatoru:** `.npmignore` vylučuje kořenový `/jest.config.js`. Spouští jen vlastní sadu
+  balíčku a po instalaci ho nic nečte: grep `conn-orch-validator/jest` nad `shared/`, `infra/` a
+  `origin/devel` všech checkoutů pod `api_biz/` (10) dal 0. `npm pack --dry-run`: 116 → 115 souborů, ubyl právě
+  `jest.config.js`; `templates/business-service/jest.config.js` a obě šablonové `tests/**` zůstávají.
+
+### Fixed — `L-PACK-TESTS` čte negace `.npmignore` / `.gitignore`: `/tests/` a pozdější `!tests/**` je nález (d.1006)
+
+Řádek četl z ignore souboru jen řádky, které `tests/` vylučují, a žádnou negaci — takže
+`.npmignore` s `/tests/` a pod ním `!tests/**` prošel jako „vyloučeno", zatímco
+`npm pack --dry-run --json` tier zabalil. Nově řádek přehrává npm procházku
+(`testsShippedBy` v `src/manifest/checks/libraryTests.js`) nad skutečnými soubory
+`tests/`: každý adresář i soubor soudí poslední řádek, který ho trefí; vyloučený adresář
+se znovu otevře, když ho pozdější `!` vzor se `/` může trefit uvnitř (začíná jménem
+adresáře nebo `**`) — vzor bez `/` (`!*.js`) ho neotevře. Nález jmenuje řádek, který tier
+vrátil: `excludes tests/, then re-includes it with "!tests/**" — …`. Pořadí `files` →
+`.npmignore` → `.gitignore` beze změny (`files` vyhrává, `.npmignore` se pak nečte).
+
+Bez nové závislosti: `npm-packlist` ani `@npmcli/arborist` balíček nemá (`npm ls` prázdné),
+a volat `npm` z PATH by bránu udělalo závislou na prostředí (`automation-gates.md` §1.1).
+Že reprodukce odpovídá npm, drží `tests/unit/libraryPackTests.npmPack.integration.test.js`:
+20 tvarů (tabulka `tests/helpers/packTestsShapes.js`, sdílená s unit sadou) změřených
+`npm pack --dry-run --json` (npm 11.12.1); bez `npm` v PATH je sada NOT RUN jménem.
+Nad 29 balíčky `api/shared/**` řádek před i po změně 0 nálezů.
+
+Exporty `ignoresTests` a `allowsTests` z `src/manifest/checks/libraryTests.js` odcházejí
+(d.1006b) — čtyři otázky `change-discipline.md` § Removing: (1) vznikly v d.211 jako
+pomocné predikáty řádku a exportovaly se vedle `checks`; (2) nesl je řádek `L-PACK-TESTS`,
+který stojí dál; (3) nečte je nikdo — mimo soubor 0 výskytů v celém `api/` (testy
+včetně) a uvnitř je nahradily `allowlistEntryReachingTests` (d.1002) a `testsShippedBy`
+(d.1006); (4) náhrada je koncepčnější: řádek odpovídá jedním výpočtem nad skutečnými
+soubory, ne predikátem nad textem. Modul exportuje jen `checks`.
+
+### Added — Tier-1 běžec zná epilog receptu: `compensationStep` a scope `global_error_handler._failure` (d.945, conf meditest-manual-trigger 009)
+
+Recept smí deklarovat `global_error_handler: { strategy: 'compensate', compensationStep: '<poslední krok>' }`.
+Běžec se teď chová jako engine (`WorkflowOrchestrator`, d.934):
+
+- běžný běh k epilogovému kroku nikdy nedojde (šťastná cesta ho nespustí);
+- recept s deklarací skončí u PRVNÍHO kroku s `passed === false` (handler vyhodil, nebo `expect`
+  nesplněn) a pak jednou spustí `compensationStep`; ve scope je pád jako
+  `{{global_error_handler._failure.<pole>}}` se šesti klíči `step_id`, `service`, `operation`,
+  `error_type`, `error_code`, `details`. `error_type` je odpověď klasifikátoru enginu (d.982, viz
+  `### Changed` níže), `error_code` a `details` jsou hodnoty vyhozené chyby, jinak `null` — nic se
+  nedomýšlí;
+- padlý epilog další epilog nespustí;
+- výsledek `runCookbook` nese aditivní `epilogue: { step_id, status, output? | error? }`, jen když
+  epilog běžel; počty kroků ani `steps` nemění;
+- recept BEZ deklarace beze změny — včetně toho, že krok bez `expect` po selhání nechá běžet další kroky.
+
+`runCookbook` nově volá `validateCookbook` z `@onlineapps/cookbook-core` (od d.980 PRVNÍ a bez
+kopií v běžci — viz `### Changed` níže). Z formátu přibývá, co běžec sám neznal:
+povinný `type` kroku, vzor `step_id` (`^[a-zA-Z0-9_]+$`), typ `workspace_id` (celé číslo — recept
+s jiným odmítne celý, hláška jmenuje cestu klíče), pravidla epilogu (d.933: tvar deklarace; d.942:
+`_failure` jen v epilogu) a odmítnutí pozičního odkazu `{{steps[0]…}}` (d.951: krok se adresuje
+`step_id`, nikdy pozicí — dosud zůstával doslovným textem).
+
+Testy a fixtury podle pravdy formátu: `type: "task"` doplněn do receptů fixtur i receptů psaných
+v testech; `step_id` s pomlčkou přejmenovány na podtržítko (`^[a-zA-Z0-9_]+$`); testy workspace
+a závorkového odkazu tvrdí odmítnutí formátem. Fixtura `v3-test-service` má operaci
+`boom-with-details`.
+
+### Removed — druhá kolej zákazu klíče `id` u kroku (`utils/cookbookFormat.readCookbookSteps`) (d.985)
+
+Zákaz klíče `id` u kroku vlastní cookbook-core (d.983: `Forbidden field 'id' at /steps/<n>/id - this key
+must not be declared here …`). Běží PRVNÍ v Tier-1 (`CookbookTestRunner.validateCookbook`, d.980) i v readiness
+cestě (`CookbookTestUtils.validateCookbook`, d.984), takže kopie v `readCookbookSteps` byla v obou cestách
+nedosažitelná. Hláška `[CookbookFormat] step "<id>" carries "id" - Expected: "step_id" only …` zaniká. Krok
+s `id` se odmítá dál, jen slovy cookbook-core; `readCookbookSteps` zůstává pro čtenáře nevalidovaného receptu
+(`compareCookbooks`, `_operationsOf`, `hasExpectClauses`) a odmítá už jen `steps`, které nejsou pole.
+Test `cookbookStepIdentity.test.js` hlídá, že literál staré hlášky v `src/` nevznikne znovu.
+
+### Changed — readiness cesta (`CookbookTestUtils.validateCookbook`) volá `validateCookbook` z `@onlineapps/cookbook-core` PRVNÍ; syntetický recept `createServiceReadinessTests` má `step_id` tvaru `test_<operace>` (d.984)
+
+Totéž, co d.980 udělal Tier-1 běžci, teď platí i pro cestu readiness wrapperu
+(`ServiceReadinessValidator.checkCookbookExecution` ← `createServiceReadinessTests`): kopie kontrol
+receptu v `CookbookTestUtils.validateCookbook` jsou pryč a odmítnutí formuluje cookbook-core. Metoda
+dál vrací `{ valid, errors }`; odmítnutí je jediná položka `errors`. Mizí tyto hlášky readiness cesty
+(vpravo podřetězec hlášky cookbook-core, která je nahrazuje):
+
+| Mizející hláška readiness cesty | Nově (cookbook-core) |
+|---|---|
+| `Cookbook is required` | `Invalid type for 'root' at /. Expected object, got null.` |
+| `cookbook format version is missing …` | `Missing required field 'version' at /.` |
+| `cookbook format version "<v>" is below the required minimum 2.1.0 …` | `FAIL-FAST: V1 format (1.x.x) is BANNED` / `FAIL-FAST: V2.0 format (2.0.x) is BANNED` |
+| `cookbook format version <v> is not a version string …` | `Invalid format for 'version' at /version. Must match pattern: ^2\.\d+\.\d+$` |
+| `[CookbookFormat] cookbook "steps" is an object, not an array …` | `Invalid type for 'steps' at /steps. Expected array, got object.` |
+| `Steps array is required` | `Missing required field 'steps' at /.` / `must NOT have fewer than 1 items (got 0 items)` |
+| `Step <i>: step_id is required` | `Missing required field 'step_id' at /steps/<i>.` |
+| `Step <i>: type is required` | `Missing required field 'type' at /steps/<i>.` |
+| `Step <i>: service is required for task steps` | `Missing required field 'service' at /steps/<i>.` |
+
+Recept, který cookbook-core odmítne, readiness cesta nově odmítne i tehdy, když ho dřív propustila
+(např. `step_id` s pomlčkou, chybějící `operation`). Jiná výjimka než `CookbookValidationError`
+z cookbook-core se nepřevádí na nález; propadne do `checkCookbookExecution`, který ji hlásí jako
+neprošlou kontrolu. Vlastní pravidlo readiness cesta nemá žádné: zákaz klíče `id` u kroku odmítá
+cookbook-core (d.983, `Forbidden field 'id' at /steps/<n>/id`) a kopie v `readCookbookSteps` zanikla
+s d.985 (`### Removed` níže).
+
+`createServiceReadinessTests` skládá syntetický recept v nové funkci `buildReadinessCookbook`
+(export modulu `helpers/createServiceReadinessTests`, veřejný export balíčku se nemění). `step_id`
+kroku je `test_<jméno operace>`, kde se každý znak mimo `[a-zA-Z0-9_]` nahradí `_` (dřív
+`test-<jméno>`, což vzor `step_id` formátu porušovalo u každé operace). Když dvě operace dostanou
+stejné `step_id`, pomocník to odmítne hláškou
+`[createServiceReadinessTests] Operations "<a>" and "<b>" map to the same step_id "<id>" - …`. Pro biz
+readiness sady (`tests/bootstrap/service-readiness.test.js`) se mění jen tvar syntetického `step_id`;
+jejich tvrzení je průchod a ten platí (ověřeno nad kopiemi `operations.json` služeb hello, converter,
+ingest, pdfgen).
+
+`utils/cookbookFormat.checkCookbookFormatVersion` ztratil posledního čtenáře a zanikl i se svými
+testy; `readCookbookSteps`, `stepIdentityOf` a `MIN_COOKBOOK_FORMAT_VERSION` zůstávají.
+
+### Changed — Tier-1 `_failure.error_type` je string z klasifikátoru enginu, ne `null` (d.982)
+
+`cookbook-core` `RunFailure.error_type` je povinný string; běžec psal `null`, takže recept, který
+`_failure` předá dál (ingest `ack-source-delivery` čte `failure.error_type` jako string), by v Tier-1
+padl na schématu. Běžec teď `error_type` získá týmž klasifikátorem jako engine:
+`ErrorClassifier.classify` z `@onlineapps/error-handler-core` — jádro, na které deleguje
+`classifyError` konektoru `@onlineapps/conn-infra-error-handler`, jehož instanci engine dostává.
+Jedna instance na běžce.
+
+- vyhozená chyba handleru → co klasifikátor vrátí pro ni (např. `ValidationError` z
+  `@onlineapps/handler-contract` → `VALIDATION`, obecný `Error` bez známého kódu a statusu → `UNKNOWN`);
+- nesplněný `expect` bez vyhozené chyby → `classify(null)` = `UNKNOWN`; Tier-1 `expect` v enginu
+  protějšek nemá, `error_code` a `details` zůstávají `null`.
+
+Nová závislost: `@onlineapps/error-handler-core` (exact pin na verzi, kterou pinuje
+`@onlineapps/conn-infra-error-handler` orchestrátoru — táž třída `ErrorClassifier`).
+Tvar `results.epilogue` a běh receptu bez deklarace epilogu se nemění.
+
+### Changed — Tier-1 běžec nedrží druhou kopii kontrol receptu: `validateCookbook` z `@onlineapps/cookbook-core` běží PRVNÍ, jeho hlášky nahrazují hlášky běžce (d.980)
+
+`CookbookTestRunner.validateCookbook()` (a tím `runCookbook`) volá nejdřív `validateCookbook`
+z `@onlineapps/cookbook-core` — tutéž funkci, na které hází přijímající strana. Kopie jeho pravidel
+v běžci jsou pryč (jedna kolej, `change-discipline.md` § One rail per concern). Co recept odmítne,
+se nemění; mění se SLOVA, která biz vlákno čte ve výstupu Tier-1 (záznam `cookbook-load-failure`
+v `results.steps[].error`, řádek chyb kroku 4 validace). Mizí tyto hlášky běžce a nahrazuje je
+hláška cookbook-core (vpravo podřetězec, který se v ní objeví):
+
+| Mizející hláška běžce | Nově (cookbook-core) |
+|---|---|
+| `[CookbookTestRunner] Cookbook is not a JSON object …` | `Invalid type for 'root' at /. Expected object, got <typ>.` |
+| `[CookbookTestRunner] cookbook format version is missing …` | `Missing required field 'version' at /.` (prázdný řetězec: `Invalid format for 'version' at /version.`) |
+| `[CookbookTestRunner] cookbook format version "<v>" is not a version string …` | `Invalid format for 'version' at /version. Must match pattern: ^2\.\d+\.\d+$` |
+| `[CookbookTestRunner] cookbook format version "<v>" is below the required minimum 2.1.0 …` | `FAIL-FAST: V1 format (1.x.x) is BANNED` / `FAIL-FAST: V2.0 format (2.0.x) is BANNED` |
+| `[CookbookTestRunner] Cookbook has no steps …` | `Missing required field 'steps' at /.` (`null`: `Invalid type for 'steps' at /steps. Expected array, got null.`) |
+| `[CookbookFormat] cookbook "steps" is an object, not an array …` | `Invalid type for 'steps' at /steps. Expected array, got object.` |
+| `[CookbookTestRunner] Cookbook must have at least one step …` | `Invalid value for 'steps' at /steps - must NOT have fewer than 1 items (got 0 items).` |
+| `[CookbookTestRunner] Step #<n> has no step_id …` | `Missing required field 'step_id' at /steps/<n-1>.` |
+| `[CookbookTestRunner] Step <id> must have service …` | `Missing required field 'service' at /steps/<i>.` (prázdný: `Invalid value for 'service' …`) |
+| `[CookbookTestRunner] Step <id> must have operation …` | `Missing required field 'operation' at /steps/<i>.` |
+| `[CookbookTestRunner] Step <id> references an undefined step …` | `Step references that cannot resolve at run time - <id>.input: {{steps.<x>…}} - unknown step '<x>'.` |
+| `… references an undefined step - "{{steps.0…}}" names "0"` | `… - a step is addressed by its step_id, never by position` |
+| `[CookbookTestRunner] Step <id> depends on an undefined step …` | `Step '<id>' depends on non-existent step_id '<x>'` |
+
+Soubor receptu se dál připojuje na konec (`(cookbook file: <cesta>)`); tvar `results`, `epilogue`,
+počty ani `kind` záznamu se nemění.
+
+`version` jiného typu než řetězec (např. číslo `2.1`) cookbook-core vlny 3 odmítá pojmenovanou vadou
+`Invalid type for 'version' at /version. Expected string, got number.` (d.983; do té doby padal
+v `detectVersion` na `TypeError`, nahlášeno s d.980).
+
+Běžci zůstává jen to, co cookbook-core nedělá: odmítnutí `test.mockInfrastructure` jménem; odmítnutí volání
+helperu `{{name(…)}}` ve vstupu kroku (Tier-1 nemá registr helperů); hodnota `workspace_id`
+(`assertWorkspaceId` při spuštění kroku). `CookbookTestRunner.validateCookbook()` nově odmítá
+i to, co dřív odmítal až `runCookbook` (povinný `type`, vzor `step_id` …), protože cookbook-core
+běží v něm.
+
+### Changed — BREAKING: `parseHandlerRef` čte tvar handler ref z `@onlineapps/service-validator-core`; export `HANDLER_REF_PATTERN` zaniká (d.962, d.465d)
+
+`src/utils/handlerRef.js` nedrží vlastní literál tvaru `handlers/<cesta>#<export>`: `parseHandlerRef` testuje
+proti `HANDLER_REF_REGEX` z veřejného vstupu `@onlineapps/service-validator-core` (export z d.720), tedy proti
+TÉMUŽ objektu, podle kterého registr odmítá `operations.json`. Dvě kopie jednoho pravidla se rozejdou v den,
+kdy se jedna opraví (`change-discipline.md` § One rail per concern). Chování se nemění — oba výrazy změřeny nad
+stejnou sadou vzorků (`handlers/a/b#fn`, `handlers/a.b#fn`, `handlers/a#1x`, `handlers//x#f` a dalších), 0 rozdílů.
+
+BREAKING: vstup balíčku už nevyváží `HANDLER_REF_PATTERN`. Čtenáři mimo balíček: 0 (změřeno
+`grep -rn --exclude-dir=node_modules` nad `api/shared`, `api/infra`, `api/scripts`, `api/templates`, `api_biz`,
+`fe_adminui`). Kdo tvar potřebuje jako hodnotu, čte `require('@onlineapps/service-validator-core').HANDLER_REF_REGEX`.
+
+Vyžaduje `@onlineapps/service-validator-core` s exportem `HANDLER_REF_REGEX` na vstupu balíčku (dnes v jeho
+`[Unreleased]`; vydaná 2.1.0 ho nemá).
+
+Stráž: `tests/unit/handlerRefSingleSource.test.js` — pod `src/` není literál `^handlers\/` ani hluboký import
+`@onlineapps/<balíček>/src/…`; `tests/unit/handlerRef.test.js` měří identitu (`jest.spyOn` na exportovaném objektu).
+
+### Fixed — unit sada nepřepisuje `manifests/biz-service.manifest.json` balíčku (d.965)
+
+Dvě sondy v `tests/unit/sharedEnvCli.test.js` přepisovaly zabalený manifest a v `finally` ho vracely, takže paralelní
+worker jestu, který ho v tu chvíli četl, dostal `[Manifest] Manifest is not valid JSON` (náhodně červený
+`templateRunnerRuntime`); sondy teď běží nad kopií manifestu v dočasném adresáři a stráž `afterEach` shodí test, který
+zabalený manifest změní (mtime nebo obsah).
+
+### Changed — Tier-1 běžec předává handleru skutečný `OperationContext` (conf handler-contract 001)
+
+`CookbookTestRunner._dispatchViaHandler` staví `ctx` jako `new OperationContext({...})` z
+`@onlineapps/handler-contract` místo objektového literálu — tutéž třídu, kterou handler dostává
+v produkci od `@onlineapps/service-wrapper`. Import jde z balíčku kontraktu (L1), ne z wrapperu (L4),
+takže běžec (L3) nemá zpětnou hranu (architecture-principles §7).
+
+Co to pro handler znamená pod běžcem:
+
+- `ctx.requireActingPerson()` vrací `step.person_id`; krok bez něj skončí 400 `VALIDATION_FAILED`
+  (dosud `TypeError: ctx.requireActingPerson is not a function`, 500).
+- `ctx.normalizeDateRange()` funguje jako v produkci (dosud `TypeError`, 500).
+- `ctx` je zmrazený (`Object.isFrozen(ctx) === true`): zápis do slotu hodí v strict mode
+  `TypeError`, stejně jako v produkci. Dosud byl literál běžce zapisovatelný.
+
+Sada slotů se NEmění (conf handler-contract 001, čtení 4): runner-only `headers` a `service_name`
+zůstávají, `config` ani `scheduler` běžec nestaví. Nová závislost `@onlineapps/handler-contract`
+`1.0.0` (exact).
+
+### Fixed — šablona biz služby nese `src/config/index.js`, ze kterého wrapper čte konfiguraci (d.957)
+
+`bootstrap(__dirname)` z `@onlineapps/service-wrapper` čte konfiguraci služby jen z `<serviceRoot>/src/config`
+a `service.env` bere z toho, co tam vrátí `ConfigLoader.loadAll({ basePath, env: process.env })`. Všech osm biz služeb
+ten soubor nese se stejným kódem; `templates/business-service` ho neměl, takže služba vytvořená `oa-sync-template --new`
+(i `scripts/add-service.sh`, který jde touž cestou) by nenabootovala. Šablona teď nese `src/config/index.js` jako
+bajtovou kopii souboru služeb converter, hello a ingest; zrcadlo `api/templates/business-service` ho nese také
+(`tests/unit/templateMirror.test.js`) a README šablony ho uvádí v § Structure. Sada `tests/unit/templateServiceConfig.test.js`
+měří, že vyrenderovaná služba soubor má a že předá loaderu kořen služby a `process.env` a vyveze, co loader vrátil
+(wrapper v ní zastupuje zapsaný stub souseda). Stávající služby se nemění.
+
+### Fixed — `oa-validate --library` nad balíčkem z jiného checkoutu skončí fail-fast, ne falešným nálezem (d.940)
+
+Běh jednoho balíčku měří balíček proti api checkoutu, za který kopie validatoru mluví (`workspaceRoot.js`
+§ apiCheckoutOf); balíček ze sourozeneckého checkoutu (typicky git worktree vedle `api/`) tak dostal `L-README-REGION`
+s fixem `npx oa-sync-template readme-uniform --all`, který by README přepsal na odkaz do cizího checkoutu, a `where`
+s jménem cizího adresáře. Nově `requirePackageInApiCheckout()` běh zastaví před prvním řádkem hláškou
+`[ManifestWorkspace] <balíček> lies outside the checkout this validator speaks for (<checkout>) - Fix: run oa-validate
+from the checkout that carries the package: node <jeho checkout>/…/oa-validate.js --library <balíček>` (exit 2); leží-li
+balíček v adresáři, nad kterým žádný checkout není, hláška to říká a příkaz nevymýšlí. Balíček uvnitř checkoutu a běh bez
+workspace (`NOT RESOLVED`) se nemění. Sada: `tests/unit/manifestWorkspaceRoot.test.js` § a package in a sibling checkout.
+
+### Changed — `only_with` je vlastnost ŘÁDKU manifestu, ne jedné kontroly (d.838)
+
+Podmíněný řádek `only_with: <cesta>` existuje od `S-INT-C`: skript, který ukazuje na sadu,
+kterou repozitář nemá, je deklarace bez obsahu. Vyhodnocovala ho ale skriptová kontrola sama
+(`checks/serviceScripts.js`), takže kterýkoli jiný druh řádku podmínku ignoroval — `only_with`
+nad `config/service/*` by v manifestu stálo a v běhu nerozhodlo nic. Pravidlo viditelné
+v deklaraci a nepřítomné v běhu je ta tichá neúčinnost, kterou `automation-gates.md` §5 počítá
+za vadu.
+
+Od téhle změny ho čte engine, který řádky rozděluje na kontroly (`manifest/runManifest.js`,
+`rowApplies`), a čte ho pro VŠECHNY scope — `service`, `workspace` i `bearer` (u nosičů per
+nosič, protože podmínka je o tom, co nese konkrétní repozitář).
+
+Chování se nemění: řádek, jehož podmínka neplatí, neodpovídá nic — žádný nález a žádné NOT RUN,
+přesně jako dosud u `S-INT-C`. NOT RUN by znamenalo „nemohl jsem posoudit"; tady není co
+posuzovat, řádek pro takovou službu neplatí. Zachována je i ta část, na které `S-INT-C` stojí:
+adresář, který existuje a je prázdný, podmínku NESPLŇUJE.
+
+Žádný nový řádek uniformy tím nevzniká — mechanismus se zobecňuje dopředu, pro podmíněný řádek
+nad `config/service/*`, který přijde s pinem po vlně, jež vydá jeho schéma.
+
+### Changed — BREAKING: veřejnou plochou balíčku je mapa `exports`, ne strom souborů (d.812)
+
+`package.json` nese mapu `exports` se čtyřmi klíči: `.` (→ `src/index.js`), `./manifests/*`, `./templates/*`
+a `./package.json`. Každá jiná cesta do balíčku — typicky `require('@onlineapps/conn-orch-validator/src/utils/deployContract.js')`
+— končí chybou `ERR_PACKAGE_PATH_NOT_EXPORTED`; interní moduly (`src/**`, včetně `src/cli/*`) přestávají být importovatelné.
+Mapy `bin` se to netýká: `oa-validate`, `oa-biz-ci-gate`, `oa-lint-scripts` i `oa-sync-template` běží dál. Schopnost, kterou
+jediný změřený konzument bral hlubokou cestou (`api/scripts/verify-biz-deploy-contract.sh`), dostala jméno na vstupním bodě:
+`verifyDeployContract`, `DEPLOY_CONTRACT_REQUIREMENTS`, `DEPLOY_CONTRACT_SCOPE`. Konzument s hlubokým `require` přejde na tyto
+exporty (nebo na `manifests/*` / `templates/*`). Mapu drží `tests/unit/packageExports.test.js`, seznam jmen vstupního bodu
+`tests/unit/indexExports.test.js`.
+
+### Fixed — varování kroku 1 (struktura) se dostanou do souhrnu validace (d.791c)
+
+`ValidationOrchestrator` z kroku 1 sbíral jen `errors`; `warnings`, které `ServiceStructureValidator` plní (např.
+`STANDARD_LEVEL_GAP`), tiše zahazoval, zatímco krok 4 je sbíral. Nově jsou v `results.warnings` se `step: structure`.
+Verdikt se nemění — nikdo ho podle počtu varování nepočítá; služba může v souhrnu uvidět varování, které tam dřív nebylo
+(změřeno nad `api_biz/*`: jedno, `STANDARD_LEVEL_GAP` u ingestu).
+
+### Changed — BREAKING: R8 permit pro `require` modulu namespace žádá vykonávaný řádek, ne zmínku (d.782b)
+
+`src/utils/deployContract.js`: permit R8 „soubor si vyžádá modul test-namespace“ se měřil nad celým textem souboru, takže
+komentář `// TODO: require('./testNamespace')` soubor z bezpečnostní hranice R8 vyvázal. Nově platí `matchesOnExecutingLine()`
+jako u ostatních permitů; regex má jméno `REQUIRE_NAMESPACE_MODULE`. Integrační test, který require nese jen v komentáři,
+je teď nález R8. Změřeno nad `api_biz/*`: 0 takových souborů, verdikt R8 se u žádné služby nemění.
+
+### Fixed — obě hlášky R8 jmenují obě cesty, které permit uznává (d.778, d.782)
+
+Finální hláška R8 i hláška o souboru, který si staví vlastní databázi a nepřesměruje `DB_NAME`, radily jen
+`require` modulu `tests/integration/testNamespace.js`. Nově jmenují obě uznávané cesty: volání `getTestNamespace()` /
+`getForeignTestNamespace()` na vykonávaném řádku, nebo `require()` modulu repozitáře. Permit se nemění, jen text hlášek.
+
+### Fixed — `createServiceReadinessTests`: deklarovaný `timeout` platí pro všechny tři registrované testy (d.764b)
+
+Volba `options.timeout` (výchozí 15000) se předávala jen prvnímu ze tří testů; zbylé dva běžely s výchozím rozpočtem jestu
+(5000). Nově ji nesou všechny tři. Neplatná hodnota (včetně `0`, které jest čte jako „bez rozpočtu“) končí fail-fast hláškou
+`[Context] … Fix:`; vynechaná volba nebo `undefined` zůstává výchozí 15000. Volajícím bez voleb se dvěma testům rozpočet
+rozšiřuje z 5000 na 15000.
+
+### Changed — cesta k proofu má v balíčku jednoho vlastníka; proof na disku nepřeskočí nic (d.758)
+
+`ValidationOrchestrator` bere cestu `conn-runtime/validation-proof.json` z `PROOF_RELATIVE_PATH` (`src/utils/preValidation.js`)
+místo vlastního literálu. Chování se nemění: nová sada `tests/unit/proofFileIsOutputNotCache.test.js` dokládá hodnotou, že
+starý proof položený na disk běh nepřeskočí a skončí přepsaný otiskem, který běh naměřil.
+
+### Fixed — citace dokumentů v hláškách a komentářích nesou tvar `api/…`; sweep nedoporučuje `service-common` (d.753b, d.753c, d.756, d.756b)
+
+Citace začínající `/` (`See: /docs/biz/…`, `@see /api/…`) a citace bez prefixu ve vytištěných `fix:` hláškách
+(`ServiceStructureValidator`, `sharedEnv`) nesou `api/docs/…` — tvar, který se ze workspace otevře a který čte `L008`.
+Sondy v `tests/unit/serviceStructureMessages.test.js` a `tests/unit/readmePointerCli.test.js` měří každou citaci v `src/**`
+(a v komentářích `tests/**`) proti disku. `ServiceStructureValidator.validatePackageJson()` přestal doporučovat
+`@onlineapps/service-common` — týž soubor import retired hierarchie chyb odmítá; odmítnutí zůstává beze změny. Konzument,
+který porovnává text hlášek doslova, uvidí nový tvar cesty. Neexportovaná konstanta `MIGRATIONS_README` (`manifest/checks/serviceDb.js`)
+bez čtenáře smazána — cestu nese řádek `D-DB-README`.
+
+### Changed — jméno README má jednoho vlastníka, `src/sync/readmeFile.js` (d.739, d.739b, d.753)
+
+`README_FILE` deklaruje jediný modul `src/sync/readmeFile.js`; `sync/readmePointer.js`, `sync/readmeLocation.js`,
+`manifest/checks/libraryDocs.js` i nápověda a hlášky `oa-sync-template` ho importují. `src/cli/oa-sync-template.js` už
+`README_FILE` nere-exportuje a `sync/readmeLocation.js` ho nevyváží (importéra mimo balíček neměl ani jeden). Vypsaný text
+se nemění (`README_FILE === 'README.md'`).
+
+### Added — `L-README` odmítá ručně psanou verzi balíčku (d.732)
+
+Kontrola řádku `L-README` (`manifest/checks/libraryDocs.js`) hlásí v README zápis `Version: X.Y.Z` a samostatné `vX.Y.Z`
+— verzi vlastní `package.json`. Holá trojice bez popisku, konfigurační příklad (`serviceVersion: '1.0.0'`) ani jméno
+závislosti (`lib-v2`) nálezem nejsou. Knihovna s verzí v README dostane od `oa-validate --library` nález.
+
+### Changed — `L-CHANGELOG` měří záznam vydávané verze, ne existenci souboru (d.731b)
+
+Řádek běží jako kontrola `library-changelog-entry`: v `CHANGELOG.md` musí existovat sekce pro verzi z `package.json`
+a nést aspoň jeden neprázdný řádek, který není podnadpis. Prerelease `X.Y.Z-rc.N` smí stát pod neprázdným `[Unreleased]`.
+Tvar nadpisu se neřeší (`## [1.0.3] — …` i `## 1.0.0`). Knihovna s prázdnou sekcí vydávané verze je nově NOT PUBLISHABLE.
+
+### Changed — BREAKING: klíče `config.json` vlastní jen řádek `C-SERVICE` (d.726)
+
+Krok 1 (`ServiceStructureValidator`) přestal žádat `service.name` vlastním seznamem; drží jen strukturu (soubor existuje,
+čte se, parsuje). Klíče žádá řádek `C-SERVICE` (`manifest/checks/serviceConfig.js`, `REQUIRED_SERVICE_KEYS`). Typ nálezu
+`MISSING_CONFIG_FIELD` zaniká — kdo ho čte, přejde na nález `C-SERVICE`. Služba bez `service.name` už neselže v kroku 1,
+takže běh nově promluví i o dalších chybějících klíčích (např. `workspaceScoped`).
+
+### Changed — `oa-sync-template --target <služba>` uvede do souladu každý generovaný řádek, i `G-SHARED-ENV` (d.710, d.710c)
+
+Holý běh psal jen řádky sekce `files`; `config/env-templates/shared.env` (řádek `G-SHARED-ENV` v sekci `config`) nezapsal,
+takže služba po syncu mohla být NOT DEPLOYABLE. Nově běh bere každý řádek, který o sobě deklaruje `"class": "generated"`,
+a bez workspace nad sebou hlásí `NOT RUN G-SHARED-ENV …`. Podpříkaz `shared-env` bere umístění SSOT i cíle z řádku
+`G-SHARED-ENV` (`from`, `path`), ne z vlastních konstant; chybějící SSOT hlásí sdílenou větou `[ManifestDiscovery] Referenced
+file not found …`. `fix` řádku `G-SHARED-ENV` je nově `npx oa-sync-template --target .`. Exporty CLI `MANIFEST_RELATIVE`
+a `SHARED_ENV_RELATIVE` smazány (bez importéra).
+
+### Fixed — R2 čte stráž předka po jobech a komentář symetricky; top-level klíč YAML má jednu definici (d.707, d.707b, d.707c, d.707d)
+
+`src/utils/deployContract.js`: stráž `git merge-base --is-ancestor` kryje `git reset --hard <commit>` jen v TÉMŽE top-level
+jobu a na dřívější pozici — stráž v sousedním jobu reset nekryje. Řádek, který začíná komentářem (`#`), neběží: zakomentovaná
+stráž nekryje a zakomentovaný `git pull`, `git merge` či `git reset --hard` se nepočítá (predikát `isCommentLine()`
+s `YAML_COMMENT_OPENERS`). Rozklad na klíče nese nový `src/utils/yamlTopLevel.js` (`topLevelKeys`, `rewritableTopLevelKeys`),
+sdílený s `src/sync/serviceTemplate.js`. Repozitář se stráží jen v jiném jobu nebo v komentáři nově dostane nález R2;
+změřeno nad `api_biz/*` a balenou šablonou: bez nálezu.
+
+### Added — generovaný `shared.env` umí nést značku `# @per-machine` (d.666)
+
+`src/sync/sharedEnv.js`: položka `config/shared-env.json` smí nést `perMachine: { reason: "<text>" }`; render pak nad `KEY=`
+napíše `# @per-machine — <reason>`, tvar, který čte `scripts/lib/env-template-markers.sh`. Neplatný tvar (ne objekt, neznámé
+pole, chybějící/prázdný/víceřádkový `reason`) končí hláškou `[SharedEnv] … Fix: …`. Zabalená kopie `shared.env` nese značku
+u `NODE_ENV`.
+
+### Fixed — hláška o chybějící proměnné v hlavičce kroku končí `Fix:` (d.657)
+
+`src/utils/resolveHeaders.js`: k dosavadní větě se připojuje `Fix:` — hodnotu nastavit v `env-active/*.env`, nebo
+dát do `headers` kroku kuchařky literál. Dosavadní text stojí před ní doslova; kdy a jakou třídou se hází, se nemění.
+
+### Fixed — `oa-sync-template` čte platformní soubory přes konvenci `api/`, ne přes jméno adresáře (d.653, W653)
+
+`shared-env` a `--new` skládaly cestu k `api/config/shared-env.json` (§ loadManifest) a
+`api/config/libraries.json` (§ loadLibraries) prostým `path.join(workspaceRoot, …)`. `api/` v čele takové
+cesty je konvence deklarujícího textu, nikdy jméno adresáře na disku (`src/manifest/workspaceRoot.js`
+hlavička), a GitLab klonuje repozitář pod jménem projektu — oba podpříkazy tedy fungovaly na stroji vývojáře
+a nikde jinde. Změřeno 2026-09-18 v obrazu jobu, jeden strom pod dvěma jmény:
+
+    infra-mono → [oa-sync-template] Missing platform env manifest - <workspace>/api/config/shared-env.json does not exist.
+    api        → [oa-sync-template] shared-env is in sync - …/config/env-templates/shared.env
+
+Cesta v té větě nepatří žádnému checkoutu toho workspace, takže podle ní nelze jednat
+(`.claude/rules/automation-gates.md` §1 požadavek 4). V CI to shodilo `tests/scripts/shared-env-sync.bats:32,39`
+a — přes `--new`, který čte oba soubory — `tests/scripts/readme-uniform-pointer.bats:248,260,302`. Obě místa
+teď procházejí `resolveWorkspacePath()`, jediným vlastníkem té konvence.
+
+### Fixed — `workspaceAbove()` pozná checkout pod jakýmkoli jménem (d.652, W652)
+
+Otázka „ve kterém workspace ten strom leží" se ptala na doslovný `api/config/services.json` nad každým
+předkem, zatímco checkout se jmenuje podle projektu GitLabu. Změřeno 2026-09-18 nad stromem `infra-mono`
+(`tests/scripts/readme-uniform-pointer.bats:241`, job `test-scripts` pipeline 2860587739): `null` pro strom,
+který ležel uvnitř téhož workspace, ze kterého běh vyšel — a `oa-sync-template readme-uniform` pak zapsaný
+soubor označil absolutní cestou, jménem, které na každém stroji znamená něco jiného. Ptá se teď
+`apiCheckoutOf()`, tedy touž jednou kolejí jako tři otázky pod ní; štítek `oa-sync-template` zůstává
+`<jméno checkoutu>/…`, což je jeho vlastní věc a tato změna se jí nedotýká.
+
+### Fixed — `where` nálezu nese konvenci `api/`, ne jméno adresáře checkoutu (d.652, W652)
+
+`checks/libraryContext.js` § whereOf skládal `where` odečtením kořene workspace od kořene nesoucího, takže
+hlavou cesty bylo **jméno adresáře** checkoutu. GitLab klonuje repozitář pod jménem projektu, a tentýž nález,
+který lokálně ukazuje na `api/shared/connector/conn-orch-validator/…/deployment.md:3`, tak v CI ukázal na
+`infra-mono/shared/connector/…` — cestu, která neexistuje pod žádným jménem, jež si čtenář může někam vložit
+(`.claude/rules/automation-gates.md` §1 požadavek 4). Změřeno 2026-09-18 v obrazu CI nad `library-workspace`
+přejmenovaným na `infra-mono`: tabulka nesla obě hlavy najednou —
+`infra-mono/shared/lib-bad-core/package.json` vedle `api/shared/connector/conn-orch-validator/README.md`,
+protože prefix už vzal `src/sync/readmeLocation.js` (d.625) a `whereOf` ne.
+
+Konvence má teď jednoho vlastníka i pro zpětný směr: `manifest/workspaceRoot.js` § workspaceRelativeOf, inverze
+k `resolveWorkspacePath` a totéž pravidlo, které `scripts/ci/lint-biz-docs.mjs` § workspaceRelativeOf aplikuje
+na své vlastní nálezy. Čtenáři jsou dva a **musí** se shodnout: `whereOf` řetězec píše a `runManifest.js`
+§ buildScopeFilter jím filtruje, které workspace-nálezy si běh v režimu služby nechá — dvě hláskování jedné
+cesty by v CI zahodila všechny nálezy o službě, které se běh ptal (`.claude/rules/change-discipline.md`
+§ One rail per concern).
+
+### Added — řádek uniformy `C-CI-CONNECTOR-ENV`: job `test` nastavuje klíče deklarovaného konektoru (d.635b, W635b)
+
+Nový řádek kategorie `config` (check `ci-connector-env`, severita `deploy`): pro každý
+`requiredConnectors.<c>: true` musí `variables:` jobu `test` v `.gitlab-ci.yml` — **mimo** blok `oa-ci v1`,
+který patří `G-CI` — nastavovat každý klíč z `CONNECTORS[c].env`. Změřeno 2026-09-18: tři testy emaileru padly
+v CI na `[RuntimeConfig] Missing environment variable - MINIO_USE_SSL`, jméno, které nečte žádný řádek služby —
+resolvuje ho `@onlineapps/conn-base-storage` (`required: true`, bez defaultu), takže `ci:gate:contract` ho
+nevidí (`node_modules` je vědomě mimo jeho rozsah) a `ci:gate:env` jen emituje šest `OA_CI_*` a neměří nic.
+Lokálně táž sada projde: běžec čte `config/env-templates/shared.env` přes `env_file`. Blok `variables:` je
+druhé doručení téže množiny, ručně opsané v osmi repech, a nic ho neporovnávalo s prvním.
+
+Řádek se klíčuje deklarací služby a množinou, kterou knihovna konektoru resolvuje bez defaultu — ne příznakem
+`required: true` v schématu knihovny, který je podmíněný (priorita explicitní config → env → default) a platí
+i pro čtyři rodiny klíčů, kde mezera není. Čte `variables:` jednoho jmenovaného jobu, ne `variables:` sidecaru
+o dvě úrovně hlouběji, a neptá se, **zda** repozitář job má — to je jiná oprava, tedy jiný řádek.
+Projektové proměnné GitLabu nevidí, proto míří jen na klíče s platformovou hodnotou v `api/config/shared-env.json`.
+Rozhodnutí vlastníka `biz-service-manifest` 013.
+
+### Changed — `CONNECTORS[minio].env` je pět klíčů, které `conn-base-storage` opravdu vyžaduje (d.635b, W635b)
+
+Z `MINIO_ENDPOINT`, `MINIO_ACTUAL_HOST` na `MINIO_ENDPOINT`, `MINIO_PORT`, `MINIO_USE_SSL`, `MINIO_ACCESS_KEY`,
+`MINIO_SECRET_KEY` — přesně ty, které `conn-base-storage/src/config.js` značí `required: true` bez defaultu.
+`MINIO_ACTUAL_HOST` mezi nimi není: je to **volitelný** override hostitele proxy (`actualHost`, bez `required`),
+takže by řádek vyžadoval klíč, který knihovna nepotřebuje; služby, které přes proxy jdou, ho deklarují tam, kde
+ho čtou — placeholder `${MINIO_ACTUAL_HOST}` v `config/service/config.json`, což je pokrytí M1. Dopad na dva
+další čtenáře téže množiny: M2 (`envContract.js`) pokrývá u služby s `minio: true` nově všech pět jmen, takže
+`--env-reads` je vydá deploy bráně (všechny osmery `shared.env` je nesou); a krok bootu
+`verifyConnectorContract` se dál ptá „aspoň jedno z nich", ale `MINIO_ACTUAL_HOST` sám o sobě už důkazem není.
+
+### Removed — `checks/scriptHeaders.js` nevyváží ani `SCRIPT_SCOPE` (d.636d, W636)
+
+Druhý re-export téhož druhu: vznikl s modulem v d.218 (`c2aa5367`) a čtenáře nikdy neměl — všichni tři
+(`oa-lint-scripts.js`, `lintScripts.js`, `lintScripts.test.js`) ho od začátku berou od vlastníka
+`src/lint/scripts/lintScripts.js`. Most řádku `S-SCRIPTS` teď vyváží jen `checks`.
+
+### Removed — `checks/scriptHeaders.js` nevyváží `API_CHECKOUT` (d.636c, W636)
+
+Jméno vzniklo s modulem v d.218 (`c2aa5367`) a čtenáře nikdy nemělo (`git grep -w` v každém commitu, který se
+symbolu dotkl). Konvenci „hlava cesty je `api/`" vlastní od d.636b `workspaceRoot.API_PREFIX`; most řádku
+`S-SCRIPTS` ji čte, ale nevydává pod druhým jménem. Věta NOT RUN se nemění a měří ji `manifestScriptHeaders`.
+
+### Documentation — příklad běhu živých DB sad nevypisuje soubory (d.636c, W636)
+
+Vývojářský příkaz v § Running the live-database suites bral dvě sady ze tří; výběr teď dělá požadavek na
+`tests/helpers/liveDatabase.js` (`npx jest $(grep -rl …)`), takže nová sada se přidá bez editace README.
+
+### Changed — prefix `api/` má jednoho vlastníka; čtenáři ho berou symbolem (d.636b, W636)
+
+`workspaceRoot.js` vyváží `API_PREFIX`; `lintScripts.js` (dosud vlastní literál `'api/'`), řádek `scripts-lint`
+a `readmeLocation.js` (dosud dvakrát hlava `WORKSPACE_MARKER`) čtou jeho hodnotu. Chování beze změny; sonda nad
+`src/**` v `manifestWorkspaceRoot.test.js` hlídá, že druhé znění prefixu nepřibude.
+
+### Documentation — § Running the live-database suites nedrží vlastní počet sad (d.636a, W636)
+
+Věta o živých DB sadách už nejmenuje „dvě“ (od d.620b jsou tři) ani je nevypisuje — seznamem je `script` jobu
+`test-validator-db` v `api/.gitlab-ci.yml` a požadavek na `tests/helpers/liveDatabase.js`.
+
+### Fixed — řádek `oa-sync-template` jmenuje blok, když měřil jen blok (d.610)
+
+U blokového řádku (`F-INIT`, `F-RUNNER`, `G-CI`) hlásí generátor `unchanged F-INIT init.sh (block "oa-deps-guard v1")` —
+porovnal jen obsah uvnitř značek, zbytek souboru je vlastnictví služby. Řádek celého souboru závorku nemá. Kdo parsuje
+výstup `oa-sync-template` doslova, uvidí u blokových řádků závorku navíc.
+
+### Changed — BREAKING: pravidla `operations.json` mají jednoho vlastníka (d.465, d.465b, d.465c)
+
+Pravidla o JEDNÉ operaci se všude (krok 1, krok 4, readiness skóre, sada `createServiceReadinessTests`, řádek `C-OPS`) ptají
+zrcadla registru `validateOperationsSchema` z `@onlineapps/service-validator-core` přes `src/utils/operationsRules.js` —
+lokální kontrola tedy nově odmítne i `mutates`, `resource_type` a klíč operace, které registr odmítá. Pravidla o DOKUMENTU
+(`src/utils/operationsDocumentRules.js`): prázdná mapa operací je všude error a `schema_version` musí být deklarován a roven
+`"3.0"`; typy nálezů kroku 1 `INVALID_OPERATIONS_STRUCTURE`, `INVALID_OPERATIONS_TYPE`, `NO_OPERATIONS` a
+`SCHEMA_VERSION_MISMATCH` zanikají ve prospěch `INVALID_OPERATIONS_DOCUMENT`. Úplnost deklarace (`input`, `output`,
+`description`) hlásí krok 4 i readiness touž větou (`operationsDeclarationFindings()`). Exportované API se nemění;
+změřeno nad `api_biz/*`: verdikty `oa-validate` před a po shodné.
+
+### Documentation — komentáře `src/**` bez čísel řádků; `setupDurationMs` rozlišuje jednorázovou a opakovanou cenu (d.795b, d.795c, d.981)
+
+Jen komentáře a docblocky, chování beze změny. `CookbookTestRunner.js` (u `setupDurationMs`
+na dvou místech) už netvrdí, že čtení `operations.json` i `require()` modulu jsou „a one-off
+cost per process": `require()` Node po prvním kroku podá z registru modulů, ale
+`resolveOperation()` čte `config/service/operations.json` z disku při každém kroku
+(změřeno d.795b: pět volání → pět čtení) (d.795b, d.795c). Čísla řádků v komentářích
+`src/**` (`createServiceReadinessTests.js`, `mocks/MockMQClient.js`, `utils/cookbookFormat.js`,
+`utils/envContract.js`, `validators/ServiceStructureValidator.js`) nahradily symboly (d.981).
+
+### Removed — `TESTING_STRATEGY.md` odstraněn (0 čtenářů) (d.1020)
+
+- Dokument nečetl žádný soubor v balíčku ani v repozitáři, a tak zmizel z repozitáře i z tarballu;
+  `npm pack --dry-run` ubral právě tento soubor. `docs/DESIGN.md` se balí dál — odkazuje na něj
+  balený `src/helpers/README.md`.
+
+## [12.2.0] — 2026-09-26
+### Changed — šablona biz CI: obraz se staví jen na `main`, produkce nasazuje digest z registru (d.671, d.671b; conf image-promotion 001)
+
+Job `build` v `templates/business-service/.gitlab-ci.yml` běží jen na `main` a před stavbou se ptá
+registru, zda tag `:$CI_COMMIT_SHA` už existuje (existuje → nestaví a vypíše digest); tag se nikdy
+nepřepíše. `deploy-production` nebere digest z dotenv artefaktu (`dependencies: []`), ale týmž
+dotazem do registru (`.oa-registry-digest`); když obraz pro commit nenajde, zastaví nasazení
+jmenovanou hláškou a nikdy nestaví náhradu. Fixtury manifestu nesou tentýž blok `oa-ci v1`;
+tvar i tělo dotazu měří `tests/unit/templateImagePromotion.test.js`
+a `tests/unit/templateImagePromotionShell.integration.test.js`.
+
 ## [12.1.1] — 2026-09-25
 
 ### Fixed — `verify-deploy-uniform.sh`: rada při checkoutu mimo `api_biz/` vede na cestu, kterou šablona skutečně deklaruje (d.899)