@onlineapps/service-common 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,540 @@
+# Changelog — @onlineapps/service-common
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+### Fixed — registryReader se připojuje přes `connectRedis`; jeho timeoutová hláška renderovala heslo z `REDIS_URL` (d.441)
+
+`registryReader.connect()` měl ve větvi, kde klienta vlastní, **druhou kolej**
+téhož mechanismu jako `connectRedis` v `src/redisClient.js`: vlastní
+`createClient({ url, socket: { connectTimeout } })`, vlastní `Promise.race`
+a vlastní `setTimeout` (`change-discipline.md` § One rail per concern). Rozdíl
+mezi kolejemi nebyl kosmetický:
+
+- Hláška při nedostupném Redisu zněla `no connection to ${redisUrl}` — tedy
+  **syrová URL včetně credentialu**. Změřeno na HEAD:
+  `… no connection to redis://registryreader:integr4tion-s3cr3t@127.0.0.1:1 within 1000ms`.
+  Je to táž třída vady, kterou pro `redisClient` zavřela d.245/d.245b
+  (`redactUrl`, `tests/unit/redisUrlNotLogged.test.js`), a tyto logy jdou do
+  Loki, takže únik je trvalý a vyhledatelný.
+- Lhůta se předávala node-redisu i závodu ve stejné hodnotě, takže pokus
+  knihovny končil až PO tvrdém stropu a socket v letu přežíval vlastní
+  `disconnect()` — přesně to, co d.437b pro `connectRedis` opravilo
+  (`CONNECT_ATTEMPT_SHARE`).
+- `client.on('error')` logoval `${CONTEXT} Redis client error: ${err.message}`
+  mimo jednotný tvar `[Redis] Error` s redigovanou URL.
+
+Nově reader ve větvi `ownsClient` jen řekne rozpočet a zbytek nechá jediné
+koleji:
+
+```js
+redis = await connectRedis({ purpose: 'registryReader', redisUrl, logger, timeoutMs: connectTimeoutMs });
+```
+
+Navenek se nemění `connectTimeoutMs` (dál strop pro `connect()`, výchozí 15 s),
+volba `redisUrl` vs. `client` ani chování s injektovaným klientem (ten reader
+neotvírá a `close()` ho nikdy nezavírá). Mění se **znění hlášky** — jednotný
+kontraktní tvar `[service-common][redisClient] Redis connection <verdikt> to
+<endpoint> - <důvod>` s původní chybou jako `cause` a s endpointem bez
+userinfo.
+
+**Zpřísnění kontraktu loggeru (breaking pro volajícího s neúplným loggerem):**
+reader si dosud ověřoval vlastní třímetodovou variantu (`info`/`warn`/`error`)
+— poslední lokální kopii kontraktu v tomto balíčku. Klient, kterého reader
+vlastní, píše do téhož objektu, takže kontrakt teď vlastní
+`@onlineapps/logger-contract` (`assertLogger`, čtyři metody včetně `debug`,
+konfirmace `connector-logger-contract` 001/004) a ověří se při KONSTRUKCI, ne
+až při `connect()`. Jediný volající mimo balíček — `api_biz/meta/index.js:72` —
+předává `wrapper.logger`, který kontrakt splňuje.
+
+Testy: `tests/unit/registryReader.connectRail.test.js` (cesta selhání bez
+credentialu, rozpočet předaný `connectRedis`, výchozí lhůta, KONTROLA úspěšného
+připojení, KONTROLA injektovaného klienta) a nový případ v
+`tests/integration/registryReader.integration.test.js` proti živému Redisu
+(odmítnutý port s credentialem v URL → hláška i log bez hesla). Počet hlášek
+v `tests/unit/error-message-contract.test.js` klesl 42 → 40: zanikla timeoutová
+hláška readeru i jeho `requireLogger`.
+
+### Changed (breaking) — kontrolu zastaralých rolí dělá injektovaná funkce, ne redis klient (d.431)
+
+`createJwtValidator({ logger, secret, excludePaths, redisClient })` testoval
+`redisClient.isOpen` a volal `redisClient.get()` — tedy API node-redis v4. Služba,
+jejíž klient je `ioredis` (`infra/api_meta_reader`), kontrolu nemohla dostat vůbec;
+tvar klienta přitom není znalost knihovny (`architecture-principles.md` §1, §8).
+
+Nový vstup je funkce a je **povinná**:
+
+```js
+createJwtValidator({ logger, secret, readRolesVersion, excludePaths })
+// readRolesVersion: (personId) => Promise<number|null>
+```
+
+- `null` = marker neexistuje → token platný (beze změny, konfirmace
+  `jwt-stale-check-fail-closed` 001).
+- odmítnutí čtenáře **nebo** odpověď, která není konečné číslo ani `null` → 503
+  `ROLES_VERSION_CHECK_UNAVAILABLE`, nikdy průchod (táž konfirmace).
+- chybějící `readRolesVersion` → výjimka při KONSTRUKCI: kontrola běží pro každý
+  platný token, takže instance, která ji neumí provést, nesmí vzniknout (§4).
+- parametr `redisClient` zaniká celý, bez přechodového tvaru (§11).
+
+Klíč čte volající, ale skládá ho z exportovaného `ROLES_VERSION_PREFIX` =
+`state:meta:person:roles_version:` — marker píše biz-meta přes konektor, který
+prefix `state:meta:` přidává, takže čtenář holého `person:roles_version:<id>`
+dostane `null` pro každou osobu a `TOKEN_STALE` nepadne nikdy (rozhodnutí
+vlastníka 2026-09-14, `redis-state-prefix` 002). README § JWT validation nese
+hotový tvar čtenáře.
+
+Volající mimo tento balíček pinují vydané 2.0.x a tímto commitem se nemění;
+překlápějí se s pinem příštího vydání: `infra/api_gateway/index.js:621`,
+`infra/api_gateway/routes/protected.js:45`, `infra/api_meta_reader/src/index.js:81`
+(a testy `infra/api_gateway/tests/integration/webhookWorkflowProjection.test.js:219`,
+`infra/api_gateway/tests/unit/authPipelineBootWindow.test.js:88`).
+
+### Fixed — token vydaný ve stejné sekundě jako marker už není TOKEN_STALE (d.430)
+
+`iat` je celý počet SEKUND zaokrouhlený dolů (RFC 7519 §4.1.6), marker je epoch
+MILISEKUND (`docs/standards/redis-key-contract.md`). Porovnání `decoded.iat * 1000 <
+versionTs` proto prohlásilo za zastaralý i token vydaný pár milisekund PO změně
+role, kterou už nese — `addMembership` zapíše `String(Date.now())` a `api_auth`
+podepíše nový token v téže sekundě. Držitel dostal pokyn obnovit token a obnovený
+token spadl do téže sekundy znovu.
+
+Porovnává se v hrubší z obou jednotek: marker se zaokrouhlí dolů na sekundy
+(`decoded.iat < Math.floor(rolesVersion / 1000)`). Token ze STEJNÉ sekundy je
+platný, token o sekundu starší je dál `TOKEN_STALE` — obojí pokryto v unit i
+integračním tieru proti živému Redisu.
+
+### Fixed — connectRedis uvolní socket na vlastní lhůtě a každé selhání hlásí jednou hláškou (d.437b)
+
+`disconnect()` z d.437 uvolní jen socket, který node-redis už přiřadil
+(`RedisSocket#disconnect`); spojení, které je pořád v letu, ho přežije a drží
+otevřený TCPWRAP handle po celou výchozí lhůtu node-redisu (5 s). Změřeno
+2026-09-14 na unit tieru balíčku: `npx jest --detectOpenHandles` hlásil
+`TCPWRAP … at connect (src/redisClient.js:138)` z
+`tests/unit/redisUrlNotLogged.test.js` a běh končil hláškou `A worker process
+has failed to exit gracefully`.
+
+Pokus node-redisu proto dostává lhůtu odvozenou z rozpočtu volajícího
+(`CONNECT_ATTEMPT_SHARE` = 0,8 × `timeoutMs`, tedy 12 s z výchozích 15 s) a
+dostane ji jako `socket.connectTimeout` — socket tak ničí knihovna, která ho
+otevřela, ještě uvnitř stropu (změřeno: 803 ms z 1000ms stropu). Vlastní závod
+na `timeoutMs` zůstává tvrdým celkovým stropem: mimo `forTests` může
+reconnect-strategie zkusit víc pokusů, takže se neruší.
+
+Každé selhání spojení teď opouští `connectRedis` jedinou hláškou ve tvaru
+`[Context] Problem - Fix` s původní chybou jako `cause` — dosud prošla
+node-redisí holá `Connection timeout` i `ECONNREFUSED` beze všeho kontextu:
+
+- lhůta (naše i ta předaná node-redisu) → `… Redis connection timeout after <timeoutMs>ms to <endpoint> - <důvod>. Fix: …`
+- jiné selhání → `… Redis connection failed to <endpoint> - <důvod>. Fix: …`; odmítnuté spojení není timeout a hláška to o něm netvrdí.
+
+Endpoint v hlášce je dál redigovaný (`loggedUrl`), takže credential se ven
+nedostane. Věta `Fix:` nově radí zvýšit `timeoutMs` — dosavadní
+`connectTimeoutMs` je vstup `registryReader`, `connectRedis` takový nikdy
+neměl. `createRedisClient` přijímá nepovinný `connectAttemptTimeoutMs` (lhůta
+JEDNOHO pokusu, ne celkový strop).
+
+### Fixed — connectRedis po neúspěšném spojení uvolní klienta, kterého otevřel (d.437)
+
+Prohraje-li `client.connect()` závod s timeoutem, běží dál — s výchozí
+reconnect-strategií donekonečna — a volající klienta na této cestě nikdy
+nedostane, takže ho nemá kdo zavřít. `connectRedis` ho teď zavírá sám
+(`client.disconnect()`, jen když je `isOpen`; selhání zavření se loguje a
+původní chybu nepřekryje).
+
+### Fixed — asserty hlášky chybějící env na znění runtime-config 1.1.0 (d.426)
+
+Po pinu `@onlineapps/runtime-config` na 1.1.0 citovaly dva asserty
+v `tests/unit/defaults.test.js` starou větu `Fix: set REDIS_URL in environment or
+pass explicit config.`; nově citují celou hlášku ve znění, které předepisuje
+`architecture-principles.md` §5 — `Fix: set REDIS_URL in env-active/*.env (or pass
+explicit config).`.
+
+### Changed (breaking) — the JWT signing secret is an input, not something the library fetches
+
+`verifyAccessToken(token)` resolved the secret itself, per call, from
+`process.env.JWT_SECRET` (`src/jwt/verifyAccessToken.js`, the deleted
+`getJwtSecret()`). A shared library that reads the environment knows where the
+platform keeps its configuration — the dependency nobody declared
+(`architecture-principles.md` §1 dependencies by constructor, §8 explicit over
+implicit; measured by INFRA-DOCS 2026-09-07, recorded in
+`docs/standards/CONCEPT_AUDIT.md` as grey).
+
+The secret is now an input on both entry points:
+
+- `verifyAccessToken(token, secret)` — second argument, required.
+- `createJwtValidator({ logger, secret, excludePaths, redisClient })` — validated
+  at CONSTRUCTION, so an instance can never exist that every request would then
+  be refused by (§4 fail-fast).
+
+A **value**, not a `getSecret()` function: `docs/standards/JWT_AUTH.md`
+§ Configuration distributes one shared secret via env/Docker secrets and knows no
+secret rotation: `grep -in rotat docs/standards/JWT_AUTH.md` returns exactly one
+line, the certificate rotation listed as a COST of the mTLS option §9 rejects. An
+injected `getSecret()` resolver would be a mechanism for a concept that does not
+exist; when rotation is decided, the parameter it replaces is one line.
+
+The caller reads the key once at boot, through the helper that composes the whole
+`Fix:` sentence (d.399):
+
+```js
+const secret = requireEnv('JWT_SECRET', 'HMAC-SHA256 signing secret', { file: 'shared.env' });
+app.use(createJwtValidator({ logger, secret, excludePaths, redisClient }));
+```
+
+**The rule about the value stays in the library**, because it is a property of
+the secret and not of where it came from: `assertSecret()` — a string of at least
+`MIN_SECRET_LENGTH` (16) characters, the minimum `JWT_AUTH.md` § Configuration
+states — is the single rail both entry points validate against.
+
+Callers outside this package still pin the published 2.0.x and are untouched by
+this commit; they move with the pin of the next release:
+`infra/api_gateway/index.js:599`, `infra/api_gateway/routes/protected.js:19`,
+`infra/api_meta_reader/src/index.js:81` (all `createJwtValidator`),
+`infra/api_delivery_endpoint/src/ws/WebSocketServer.js:124` and
+`infra/api_delivery_endpoint/src/routes/workflows.js:31` (both
+`verifyAccessToken`).
+
+#### `getJwtSecret()` deleted — the four questions (`change-discipline.md` § Removing)
+
+1. **Why it existed.** It was the verifier's only way to a secret: with no
+   injection point, the library resolved `JWT_SECRET` itself so that every
+   service verifying a token got the same key and the same fail-fast on a
+   missing or too-short value.
+2. **Which part of the concept carried it.** `docs/standards/JWT_AUTH.md`
+   § Configuration — one shared `JWT_SECRET`, minimum 16 characters, identical
+   across every service that validates a JWT — and `gateway-jwt-failfast` 001, a
+   boot that dies on an absent key rather than serving unauthenticated traffic.
+   Both still stand: the key, the minimum and the fail-fast are unchanged. Only
+   the PLACE that reads the environment moves, from the library to the service
+   that owns its configuration.
+3. **Why nothing reads it.** Nothing outside this file ever did: it was absent
+   from `src/jwt/index.js` and from `src/index.js`, so no consumer could import
+   it (`grep -rn getJwtSecret` over `api`, `api_biz`, `fe_adminui` finds only
+   `infra/api_auth/src/tokenService.js:9`, a private function of the same name in
+   the token ISSUER, which is a different service and is not touched here). Its
+   one reader was `verifyAccessToken`, three lines below it, and that reader now
+   receives the value.
+4. **Is the replacement more conceptual?** Yes. The secret as a parameter is the
+   principle the function violated, and the env read lands where the concept
+   already puts configuration: at the boot of the owning service, through
+   `requireEnv('JWT_SECRET', …, { file: 'shared.env' })`, which names the key,
+   the owning env file and the fix in one sentence. A pure `getJwtSecret()`
+   kept "without env" would have been a rename of the hole: whoever called it
+   would still be asking the library where secrets live.
+
+Tests: `tests/unit/jwt/verifyAccessToken.test.js` and
+`tests/unit/jwt/createJwtValidator.test.js` now run with a DIFFERENT valid secret
+in `process.env.JWT_SECRET` throughout, so a re-introduced environment read fails
+the happy path of both files, not only the one case that names it; the same
+control runs against the live Redis in
+`tests/integration/jwtValidator.rolesVersion.integration.test.js`.
+
+### Unchanged — the four infrastructure-health wait defaults keep their readers, and the reason is now asserted
+
+`infrastructureHealthWaitMaxTimeMs`, `infrastructureHealthWaitCheckIntervalMs`,
+`infrastructureHealthQueueWaitMaxTimeMs` and
+`infrastructureHealthQueueWaitCheckIntervalMs` were put up for deletion as
+declarations with no production reader
+(`infra/api_services_registry/tests/unit/infrastructureHealthConfigShape.test.js:14-18`).
+The four questions `change-discipline.md` § Removing requires say keep, because
+question 3 fails on the evidence:
+
+1. **Why they exist.** So `waitForInfrastructureReady()` and
+   `waitForHealthCheckQueueReady()` have a platform limit and probe interval when
+   the caller names none — a service that boots before the infrastructure has to
+   wait, not die.
+2. **Which part of the concept carries them.** The boot wait on
+   `infrastructure:health:all`, documented in
+   `docs/operations/infrastructure-troubleshooting.md` § — *"up to the limit
+   `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME`"* — and run at gateway boot. It stands.
+3. **Why nothing reads them.** It does. Each of the four is read in this package,
+   in the function it exists for: `waitForInfrastructureReady.js:66-67` and
+   `waitForHealthCheckQueueReady.js:58-59`, via `runtimeCfg.get(key, override)`.
+   The INFRA measurement is true but narrower than its wording: it says the
+   REGISTRY does not take these four from `getInfrastructureHealthConfig()`.
+4. **Is the replacement more conceptual?** There is nothing to replace them with.
+   Deleting them would leave both wait functions with no limit of their own.
+
+So nothing was deleted, and `tests/unit/healthTimingOwnership.test.js` — which
+already owns "who owns which health timing" — now states it by value: each key's
+default, the file that reads it, and the environment variable that overrides it,
+with a control case proving the probe would notice a reader that disappeared.
+Measured against itself: removing one default and one reader turns three of those
+cases red.
+
+**One rail is still two, and the other half is not ours.**
+`getInfrastructureHealthConfig()` returns the same four values a second time, and
+`infra/api_gateway/index.js:526-534` plus
+`infra/api_delivery_dispatcher/src/services/DeliveryDispatcher.js:167-168, 227`
+read them from there only to hand them straight back to
+`waitForInfrastructureReady()` as `maxWait`/`checkInterval` — the same env key
+resolved twice, the second resolution posing as an override of itself. The fields
+stay because the gateway fail-fasts on a missing one, so removing them here would
+stop a boot before those two callers stop reading: a gate lands with compliance,
+never ahead of it (`automation-gates.md` §3), and the compliance is in a tree this
+package must not edit. The shape is pinned so nobody removes it early — or widens
+it.
+
+### Changed — the `Fix:` sentence is composed by the helper, not by the caller
+
+`architecture-principles.md` §5 requires a missing key to be reported with
+`Fix: set <ENV_KEY> in env-active/*.env (or pass explicit config).` The helper
+did not write it: `requireEnv()` appended `description` and stopped, so the
+sentence appeared exactly where somebody had typed it into that description by
+hand. Measured across the platform: six call sites, all in
+`infra/api_delivery_endpoint/src/config.js`, and nowhere else. Every other
+required key on the platform — `RABBITMQ_URL` in the dispatcher, `REDIS_URL` in
+the gateway and in `ServiceWrapper`, `SECRETS_MASTER_KEY` — failed with no fix at
+all. A rule that holds only where somebody remembered it is enforced by review,
+not by a mechanism (`automation-gates.md` §5); this moves it into the mechanism.
+
+`requireEnv`, `requireNumberEnv`, `requireFloatEnv` and `requireBoolEnv` now take
+a third argument, `{ file }`, and compose the whole sentence themselves:
+
+- with the owning file: `Fix: set REDIS_URL in config/env-active/shared.env.`
+- without it: §5's own generic wording, verbatim.
+
+The file is a **bare name** (`shared.env`); the helper writes the
+`config/env-active/` prefix, so the message has one shape rather than as many as
+there are spellings. A value carrying a path, or not ending in `.env`, is refused
+**at the call**, not the day the key goes missing — a typo must fail on the happy
+path too (principle 4).
+
+Why the file is an input and not a derivation, measured in d.399:
+`api/config/shared-env.json` is the single owner of the platform's shared key set
+and would answer "which file carries this key" — but only build-time tooling
+reads it (`oa-sync-template shared-env` in `@onlineapps/conn-orch-validator`). It
+is absent from a service's runtime; a biz repository does not carry it at all. A
+library resolving it through `__dirname`/cwd would break principle 1 and invent a
+second map of the same fact. So the call site names the file, the declaration
+stays the authority review checks it against, and no second map exists.
+
+The message is built as ONE template literal rather than assembled from parts,
+because `tests/unit/error-message-contract.test.js` reads throws statically: a
+message it cannot resolve is reported as context-less, and a probe that cannot
+see is not a mechanism. Its census moved 40 → 41 with the new fail-fast on a
+malformed `options.file`.
+
+### `INFRASTRUCTURE_HEALTH_REDIS_TTL` má jediného vlastníka — registr; druhá deklarace pryč (d.391)
+
+`defaults.js` deklaroval `infrastructureHealthRedisTtlSeconds: 30`, `config.js` k tomu
+env `INFRASTRUCTURE_HEALTH_REDIS_TTL` a `getInfrastructureHealthConfig()` to vydával jako
+`redisKeyTTL`. Nikdo to nečetl a hodnota byla navíc nepravdivá.
+
+**Čtyři otázky `change-discipline.md` § Removing:**
+
+1. **Proč vznikla:** hlavička `defaults.js` to říká sama — „Keep infra-related defaults
+   here to avoid duplication across files". Blok health timingů měl mít jednoho vlastníka
+   a TTL Redis klíče do něj bylo počítáno.
+2. **Která část koncepce ji nesla a stojí dál:** „jeden vlastník bloku health timingů"
+   platí — jen jmenuje špatného vlastníka. Redis klíč `infrastructure:health:*` píše
+   **jedině registr** (`infrastructureHealthTracker.js`, `setEx(key, this.redisKeyTTL, …)`)
+   a hodnota dává smysl jen vedle prahu, který musí přežít (`gracePeriod` 60 s); ten práh
+   tenhle balíček nedeklaruje a deklarovat nemá.
+3. **Proč to dnes nikdo nečte:** registr přestal spreadovat celý
+   `getInfrastructureHealthConfig()` a bere z něj přesně dva klíče — `queueName`
+   (`config.js:28`) a `publishInterval` (`config.js:296`); zbytek bloku si deklaruje sám
+   (`redisKeyTTL: optionalNumberEnv('INFRASTRUCTURE_HEALTH_REDIS_TTL', 90)`, `config.js:316`).
+   Změřeno 2026-09-14 grepem `redisKeyTTL` přes všechny `src` adresáře `infra`, `shared`
+   i `api_biz` (pozitivní kontrola `publishInterval` = 10 shod): mimo registr a samotnou
+   deklaraci nula čtenářů.
+4. **Je náhrada koncepčnější:** ano. Hodnota stojí v bloku, kde je vidět invariant
+   „TTL > gracePeriod", a je jenom jedna. Druhá kopie mohla s tou první už jen nesouhlasit
+   — a nesouhlasila: 30 versus živých 90 (3× interval sondy).
+
+Sady: unit **260 → 265/265** (nová `tests/unit/healthTimingOwnership.test.js`, 5 testů:
+klíč pryč z defaultů, pryč z výstupu getteru, env `INFRASTRUCTURE_HEALTH_REDIS_TTL=777`
+výstup nezmění, a dva kontrolní — `queueName`/`publishInterval` beze změny, blok má přesně
+zbylých osm klíčů). Integrace **33/33** beze změny.
+
+### Záložní e-mail monitoringu: sdílené spojení a opakování dočasného odmítnutí (d.318)
+
+`sendMonitoringFailFallbackEmail` otevíral na každý mail nové TCP+TLS+AUTH
+spojení. Změřeno INFRA-monitoringem 2026-09-11: sedm epizod `service_down`
+v jedné sekundě, relay odpověděl `421 4.7.0 … too many connections` **18×**
+a **12 poplachů** skončilo nedoručeno, protože je nic neopakovalo.
+
+- **Pool.** Transport má `pool: true` a meze `maxConnections` / `maxMessages` /
+  `rateDelta` / `rateLimit` jako **deklarované konfigurační klíče**
+  (`INFRA_REPORT_SMTP_MAX_CONNECTIONS`, `…_MAX_MESSAGES`, `…_RATE_DELTA`,
+  `…_RATE_LIMIT`), žádné literály v těle. Výchozí hodnoty jsou **odvozené**
+  z limitů relay zapsaných v konfirmaci `alert-smtp-relay` 003 (20 spojení /
+  10 AUTH za 60 s): jedno sdílené spojení = jedna autentizace na celou dávku.
+- **Opakování 4xx patří transportu.** Dočasné odmítnutí (4yz, RFC 5321 §4.2.1)
+  se opakuje zde, ohraničeně (`INFRA_REPORT_SMTP_MAX_ATTEMPTS`, výchozí 3)
+  a s rozestupem pod limitem relay (`INFRA_REPORT_SMTP_RETRY_DELAY`, výchozí
+  6 000 ms = 60 000/10, backoff se zdvojuje); volající dostane **jeden** verdikt,
+  až je po opakováních. 5yz je permanentní a neopakuje se; chyba **bez** kódu
+  odpovědi (mrtvý socket, padlý TLS handshake) se za dočasnou nepovažuje.
+  Umístění plyne z `delivery-mail-channel` 001 bodu 5 („a refused send is the
+  mail service's provider retry") — pro kanál poplachů je „mail service" tento
+  modul, takže druhá smyčka u konzumenta by byla zakázané zdvojení.
+- **Fail-fast** na `INFRA_REPORT_SMTP_MAX_ATTEMPTS < 1`: to není „bez
+  opakování", je to smyčka, která nikdy neodešle.
+- Logovací řádky `Email sent` / `Email send failed` nově nesou `attempts` —
+  verdikt je jeden, tak kolik pokusů stál, je vidět jen tam.
+- README dostalo oddíl o této funkci a v něm **návrh** písemného zdůvodnění
+  druhé mailové koleje (podmínka `delivery-mail-channel` 001 § Conditions →
+  `duplicity-justification` 001). Je označen jako PROPOSAL: platí až jej
+  vlastník přijme.
+
+### Marker změny rolí se čte plným klíčem `state:meta:person:roles_version:` (d.382)
+
+`ROLES_VERSION_PREFIX` byl holý `person:roles_version:`, ale zapisovatel markeru —
+služba `biz-meta` — ho píše skrz svou stavovou projekci, tedy pod `state:meta:`.
+Čtenář a zapisovatel se tak nikdy nepotkali: `TOKEN_STALE` po změně členství
+nepadalo, protože klíč, který validátor četl, nikdo nezapisoval.
+
+- **Kontrakt je plný klíč** `state:meta:person:roles_version:<person_id>` — týž
+  tvar, jakým platforma čte každou jinou projekci meta (entitlementy, kredity,
+  secrets). Rozhodnutí vlastníka 2026-09-14, konfirmace `redis-state-prefix` 002;
+  zamítnuta varianta „holý klíč mimo prefix" (klíč bez vlastníka prefixu, bez
+  obnovy z DB, druhá kolej v konektoru kvůli jedinému klíči).
+- Exportovaná konstanta `ROLES_VERSION_PREFIX` zůstává jménem i významem; mění se
+  jen její hodnota. Obě hlášky, které ji citují — 401 `TOKEN_PERSON_ID_MISSING`
+  a 503 `ROLES_VERSION_CHECK_UNAVAILABLE` — nesou plný klíč, takže čtenář hlášky
+  míří na místo, kde marker opravdu je. Nově to tvrdí i testy.
+- Testy tvrdí **kontrakt, ne kód**: unit i integrační tier píší a očekávají klíč
+  jako literál, ne přes exportovanou konstantu. Fixtura odvozená z konstanty se
+  sveze s jakoukoli hodnotou a zůstane zelená i pro špatný prefix — přesně to tuto
+  vadu drželo neviditelnou. Integrační tier píše marker do skutečného Redisu.
+- **Chování se do vydání a pinu v gateway + meta-readeru nemění**: dokud tyto dvě
+  služby nepinují novou verzi, `TOKEN_STALE` dál nepadá — stav jako dnes, ne horší.
+  Projekci markeru z `tenant_membership` dluží `biz-meta` (tamtéž, § Conditions).
+
+### `nodemailer` `^6.9.8` → `^10.0.9` — dvanáct advisories v jednom bumpu (d.317)
+
+`npm audit --omit=dev` hlásil na `nodemailer <=9.1.0` dvanáct advisories
+(`high`), mezi nimi GHSA-p6gq-j5cr-w38f (`raw` obchází
+`disableFileAccess`/`disableUrlAccess` → čtení souborů a SSRF, fix až 9.0.6),
+GHSA-rcmh-qjqh-p98v a GHSA-2x7j-588g-ccc2 (DoS v `addressparser`) a
+GHSA-c7w3-x93f-qmm8 (SMTP command injection přes `envelope.size`). Rozsah
+`^6.9.8` na žádnou opravu nedosáhl, takže je knihovna vlekla do každého stromu,
+který ji pinuje (INFRA změřila 8 stromů, `api/shared/TODO.md` § Od vlákna INFRA
+(2026-08-31, dávka 128) a § Od INFRA (2026-09-09, 4)).
+
+Čtyři majory mezi 6 a 10 a co z nich se nás týká: **7.0.0** vyhodil staré SES
+SDK (nepoužíváme, transport je SMTP), **8.0.0** přejmenoval chybový kód
+`NoAuth` → `ENOAUTH` (nevětvíme na něj — `monitoringFallbackEmail.js` kód jen
+loguje), **9.0.0** zapnul ověřování TLS certifikátu při stahování vzdáleného
+obsahu a v OAuth2/proxy (ani jedno nepoužíváme), **10.0.0** zvedl minimum na
+Node 20 (máme `>=24.0.0 <25`) a přepsal balíček do TypeScriptu s CJS i ESM
+buildem — `require('nodemailer').createTransport` zůstává funkce (změřeno).
+
+Chování transportu se NEMĚNÍ: `createTransport({host, port, secure,
+requireTLS, auth})` a `sendMail()` jsou beze změny. Doložil to integrační test
+`tests/integration/monitoringFallbackEmailStarttls.integration.test.js` proti
+skutečnému SMTP dialogu — relay bez STARTTLS dostane `EHLO`, `STARTTLS`, a
+konec; heslo na drát nejde, kód chyby je pořád `ETLS` a hláška `Error upgrading
+connection with STARTTLS: 502 5.5.1 Command not implemented` doslova. Naměřená
+verze v komentářích toho testu je proto přepsaná na 10.0.9.
+
+`npm audit --omit=dev`: **1 high → 0 zranitelností**. Sady: unit 253/253,
+integrace 29/29.
+
+### `getCriticalConfigWithFallbacks()` smazán — jméno bez těla i bez konzumenta (d.257d)
+
+Funkce měla tělo `return getCriticalConfig();` a vlastní komentář přiznával
+„kept for compatibility but DOES NOT provide fallbacks". Jméno tedy slibovalo
+přesný opak toho, co dělalo, a `architecture-principles.md` §11 (žádné
+přechodové shimy před produkcí) takovou deklaraci zakazuje. Čtyři otázky
+`.claude/rules/change-discipline.md` § Removing (konfirmace
+`declaration-removal` 001):
+
+1. **Proč vznikla.** `9133ffa8` („unified infrastructure client config with ENV
+   priority") ji zavedl s **opravdovými** hardcoded fallbacky pro
+   docker-compose — `redis://api_node_cache:6379`,
+   `amqp://guest:guest@api_services_queuer:5672` — a v témže commitu označil
+   `getCriticalConfig` za `DEPRECATED - use getCriticalConfigWithFallbacks()
+   instead`. Byla to tehdy doporučená cesta.
+2. **Která část koncepce ji nesla a stojí-li dál.** „Knihovna zná topologii a
+   dosadí ji, když env chybí." Ta část **nestojí**: `architecture-principles.md`
+   §2 (No Hardcoded Values), §3 (No Fallbacks) a rozhodnutí, že topologie je
+   fail-fast bez defaultů.
+3. **Proč ji dnes nikdo nečte.** `a0f0a04c` („rollout: enforce strict runtime
+   config") jí vzal tělo, takže zbylo jméno delegující na `getCriticalConfig`;
+   poslední konzument (mock v `monitoring-core`) padl v `e58a0afa` (d.154a).
+   Role se přesně obrátily — deprecated je dnes ta funkce, ne `getCriticalConfig`.
+4. **Je náhrada koncepčnější?** Ano. `getCriticalConfig` je fail-fast a jeho
+   hláška pojmenuje klíč i fix. Proto „smazat", ne „zapojit".
+
+Konzumenti: **nula** v produkčním kódu celého workspace (`grep` přes
+`*.js`/`*.json`/`*.md` mimo `node_modules`; jediné zbylé výskyty byly deklarace
+a testy). Nález a doporučení „smazat, testy přesměrovat" na sobě mělo vlákno
+INFRA-DOCS od 2026-09-02 (`api/shared/TODO.md`, dávka 103) — tahle změna ho
+provádí.
+
+Chování, na kterém záleží, zůstává pokryté: test fail-fastu při chybějící
+`REDIS_URL` se v `tests/unit/defaults.test.js` přesunul na `getCriticalConfig`,
+včetně doslovné hlášky.
+
+### Čísla z prostředí čte resolver — `requireNumberEnv` deleguje, `requireFloatEnv` přibyl (d.257)
+
+`requireNumberEnv()` parsoval hodnotu vlastním `Number(raw)` s vlastní hláškou
+`[ServiceConfig] … must be a number`, zatímco sesterský `optionalNumberEnv()`
+šel přes `@onlineapps/runtime-config` `type: 'number'`. Dvě definice toho, co je
+číslo, nad jedněmi a týmiž env klíči
+(`.claude/rules/change-discipline.md` § One rail per concern). Nově obě jdou
+přes resolver: koerci i hlášku o chybném tvaru vlastní výhradně on, duplicitní
+parsování v service-common zmizelo.
+
+Ostrost celočíselné koerce **následuje pin resolveru**, ne tuhle změnu: s dnešním
+`@onlineapps/runtime-config` 1.0.3 se neceločíselná hodnota pořád ořízne
+`parseInt`em, s vydáním d.253 (`type: 'number'` = jen celé číslo) bude odmítnuta.
+Proto unit testy ověřují **kontrakt delegace** (jaké schéma helper resolveru
+předá a že vrátí jeho hodnotu beze změny), ne koerci samu — ta patří testům
+resolveru.
+
+Přibyl `requireFloatEnv(name, description)` → `type: 'float'` pro klíče, které
+jsou poměrem nebo faktorem, ne počtem. Volba mezi oběma kolejemi je vlastnost
+klíče, a proto patří na volání.
+
+⚠️ **Kaskáda:** `TRACE_COMPLETION_RATE_THRESHOLD` (api_monitoring `index.js:211`,
+hodnota `0.8`) musí přejít na `requireFloatEnv` ve stejném kaskádovém commitu
+jako pin service-common — jinak monitoring buď tiše ztratí alert (dnes: `0.8` →
+`0`, a watchdog nulu přijímá jako legitimní práh,
+`watchers/workflowWatchdog.js:204-208`), nebo nenabootuje (po vlně). Je to jediný
+desetinný klíč ze 33, které přes `requireNumberEnv` jdou — změřeno d.257 proti
+`config/env-active/*.env`.
+
+Tvar hlášky o **chybějící** proměnné se nemění:
+`[ServiceConfig] Missing environment variable - <NAME> is required. <popis>`,
+společný pro `requireEnv` / `requireNumberEnv` / `requireFloatEnv` /
+`requireBoolEnv`.
+
+### `requireTLS: true` u záložního e-mailu monitoringu (d.231)
+
+`monitoringFallbackEmail.js` stavěl nodemailer transport bez `requireTLS`, takže
+proti relayi s `smtpd_tls_security_level = may` by při chybějícím STARTTLS odešlo
+`AUTH PLAIN` po nešifrovaném soketu. Flag je nastaven bezpodmínečně (u implicitního
+TLS na 465 nic nemění, žádná větev podle prostředí). Integrační test staví SMTP
+server bez STARTTLS na loopbacku: odeslání je odmítnuto (`ETLS`) a server `AUTH`
+nikdy nedostane; kontrolní klient bez požadavku STARTTLS `AUTH` odešle.
+
+### `redactUrl()` — připojovací URL v logu bez credentialu (d.245)
+
+`REDIS_URL` nese heslo k Redisu (jedna kolej, rozhodnutí leada INFRA
+2026-09-10), takže každé místo, které URL logovalo doslova, byl únik do Loki.
+Nový `redactUrl(url)` (`src/redactUrl.js`, exportován z indexu) vrací totéž URL
+bez userinfo — `redis://:heslo@cache:6379` → `redis://cache:6379`. Hodnota,
+která není URL s hostitelem, se nahradí `<unparseable-url>`; neechuje se
+(`new URL('cache-host:6379')` uspěje a přečte `cache-host:` jako schéma, proto
+ta kontrola).
+
+Předěláno na něj na třech místech, která URL psala doslova:
+
+- `src/infrastructure/waitForInfrastructureReady.js` — `Redis URL: …` při každém bootu
+- `src/infrastructure/waitForHealthCheckQueueReady.js` — totéž
+- `src/redisClient.js` — `url` v payloadu každého `[Redis] Error`
+
+Doplněno v d.245b i na zbylá tři místa v `connectRedis()` — obě hlášky
+`[Redis] Connected` (úspěšná cesta, každý boot) a text timeoutové chyby. Aby se
+redakce odvodila jednou na klienta, vrací `createRedisClient()` nově vedle `url`
+i `loggedUrl`: `url` je skutečná adresa a jde klientovi, `loggedUrl` je jediná,
+která smí do logu nebo do textu chyby. Šest míst ze šesti.
+
+## [2.0.1] — 2026-08-29
+
+- Changelog started with this release; the history before it is in git (`git log -- shared/service-common`).