Status: Accepted Datum: 2026-05-19 Accepted: 2026-05-19 — accepted by product owner (all Open Decisions OD-1..OD-7 locked; implementation sequencing F1→F2→F3→F4→F5 confirmed) Oblast: Platform doménový model / Multi-tenancy / Hosting / Billing Supersedes: — Rozšiřuje: ADR-015 (per-tenant namespace), ADR-023 §5/§7 (per-tenant-env data-plane, escape hatch), ADR-024 (worker per tenant-environment) Navazuje na: ADR-022 (publish workflow — dnešní implicitní 2 prostředí), ADR-103 (hosting cost allocation / tiers), UC-10009 DESIGN (postpaid hosting)

LOCKED DECISIONS (závazné — product owner schválil 2026-05-19)

Níže uvedená rozhodnutí jsou zamčená a závazná pro veškerou implementaci. Nesmí se přehodnocovat bez explicitního souhlasu product ownera. Detailní implementovatelné UC jsou v UC-10_stripe-billing (F1–F5).

NEsuperseeduje žádné existující ADR. Environment je nadřazená doménová abstrakce, do které se existující koncepty (tenant namespace, per-tenant-env data-plane, worker-per-tenant-env) zasazují — nikoli je ruší. ADR-015, ADR-023, ADR-024 zůstávají platné a autoritativní pro své vrstvy; tento ADR jim dává společný doménový rámec a explicitní user-facing entitu.

Context

Co je dnes „environment-like” implicitně

TalkIDE dnes nemá entitu Environment. Místo toho existují dvě implicitní prostředí odvozená ze sloupce builds.env ∈ {dev, prod} (ADR-022 §1, §4):

Faktický stav (ověřeno z ADR-015 §1, ADR-022 §4, ADR-023 ř.460):

• Namespace model = tenant-{slug}, JEDEN namespace per tenant. Preview i published prod pody dnes běží ve stejném tenant-{slug} namespace; liší se jen hodnotou builds.env a hostem ingressu.
• mirek-dev / mirek-prod (namespace-per-tenant-env) z ADR-024 §1 a ADR-023 §5 je separátní budoucí workstream, dnes NEaktivní (ADR-023 ř.460: „namespace per tenant-environment je separátní workstream”). Worker extrakce (ADR-024) na něm závisí jako na substrátu.
• Data-plane (ADR-023): schema-per-app v jedné sdílené talkide_dataplane DB; per-app schema klíčované (slug, env) → K8s Secret app-{slug}-{env}-db. ADR-023 §7 escape hatch = dedikovaný DB cluster per tenant-environment jako premium plán (NEimplementováno).

Driver tohoto ADR (zadání usera)

User chce Environment jako first-class entitu vedle Project a Domain:

• User si vytvoří libovolný počet prostředí. Prostředí = MÍSTO, kde reálně běží infrastruktura usera (compute + db + storage).
• Každý user má 1 výchozí nesmazatelné prostředí „TalkIDE” = sdílená infrastruktura, kterou máme dnes (sdílený k8s cluster, sdílený DB cluster, sdílené storage). V „TalkIDE” prostředí běží Preview + talkide-worker (AI runtime, ADR-024).
• Další prostředí (TEST, PROD, …) si user vytvoří a u každého zvolí, zda resources (compute, db, storage) běží shared nebo vlastní (dedicated) — a s jakou konfigurací.
• Plný multi-env hned (user explicitně: vytváření více prostředí + výběr shared/dedicated + konfigurace — ne minimální řez).

Dvě billing vrstvy (potvrzeno userem — viz UC-10009)

Důsledek: dřívější DP-4 intra-namespace „hosting vs ai-dev” label-split (be#125) se z velké části rozpouští — attribution je per-prostředí (≈ per-namespace; OpenCost aggregate=namespace to umí nativně). Viz sekce „be#125 disposition” níže a UC-10009 revize.

Decision

1. Environment jako first-class entita

Zavádí se nová doménová entita environment (uživatelsky „Prostředí”), rovnocenná project a (budoucí) domain. Environment patří tenantovi (konzistentní s ADR-015: namespace patří tenantovi, ne uživateli; v alfě 1 tenant ≈ 1 user).

tenant (EXISTUJE)
  └─ environment (NOVÁ)  1:N
        ├─ kind            DEFAULT | USER_CREATED
        ├─ name            "TalkIDE" (default) | user-zvolené ("TEST","PROD",…)
        ├─ slug            env-slug (RFC-1123, unikátní v rámci tenanta)
        ├─ resource_mode   SHARED | DEDICATED
        ├─ status          ACTIVE | SUSPENDED | DEPROVISIONING
        ├─ config          (JSON/struct — sizing, db tier, storage tier; sekce 4)
        ├─ deletable       BOOLEAN  (false pro DEFAULT „TalkIDE")
        └─ created_at / updated_at

project (EXISTUJE) ─── N:M (přes deployment-target) ──→ environment
domain  (EXISTUJE/budoucí) ─── N:1 ──→ environment

Vztah Project → Environment. Projekt se nasazuje do prostředí. Dnešní implicitní model (preview + published prod) se mapuje na:

• Preview = nasazení projektu do prostředí „TalkIDE” (default, shared), env=dev ekvivalent.
• Published prod = nasazení projektu do prostředí, které si user zvolí jako prod cíl Publishe — defaultně může zůstat „TalkIDE”, nebo user-created prostředí (TEST/PROD, shared nebo dedicated).

Projekt může mít více aktivních nasazení (preview v „TalkIDE” + published do „PROD”) současně — to formalizuje dnešní paralelní preview+prod (ADR-022), nově ale prod cíl je volitelné prostředí, ne fixně „tentýž tenant-ns”.

Vztah Domain → Environment. Doména (custom doména / <slug>.talkide.app) směřuje na konkrétní prostředí. <uuid>.talkide.app (preview) → „TalkIDE”; <slug>.talkide.app (published) → prod cílové prostředí. Custom domény (budoucí) se navážou na zvolené prostředí.

2. Default nesmazatelné prostředí „TalkIDE”

Každý tenant má právě jedno prostředí kind=DEFAULT, name="TalkIDE", resource_mode=SHARED, deletable=false. Vzniká lazy (konzistentní s ADR-015 §6 lazy namespace) při prvním úkonu, který prostředí vyžaduje (první Create Project / první Publish), NE při registraci.

• „TalkIDE” = přesně dnešní sdílená infrastruktura: sdílený K8s cluster, sdílený talkide_dataplane DB cluster (ADR-023 §4), sdílené NFS/Spaces.
• V „TalkIDE” běží Preview (<uuid>.talkide.app) a talkide-worker (ADR-024 AI runtime) — tedy AI vývojový loop má vždy domov ve sdíleném default prostředí, které nelze smazat ani suspendovat za neplacení infry (viz Open Decision OD-2 — finální chování default env při neplacení rozhoduje user).
• deletable=false je tvrdý invariant na BE i FE (Delete Environment UC odmítne DEFAULT s 409 CONFLICT_ENVIRONMENT_NOT_DELETABLE).

3. Namespace mapping — Environment ⇒ namespace

Tohle je most mezi novou entitou a existujícím ADR-015 / ADR-023 §5 / ADR-024.

Cílový invariant: jedno prostředí ⇒ jeden K8s namespace (jednotka kvóty, domov worker podu, domov build/test Jobů, jednotka cost attribution).

Klíčové pozorování: Environment koncept aktivuje namespace-per-tenant-env split z ADR-023 §5 / ADR-024 — to, co bylo „separátní budoucí workstream”, dostává doménový owner (entita Environment) a user-facing důvod existence (user si prostředí explicitně vytváří). Migrace ze současného tenant-{slug} (jedno ns, oba env) na per-environment ns je fázovaná (sekce „Migrační plán”).

Naming bezpečnost: env-slug RFC-1123 validace (analogie talkide-be#44 pro tenant slug). Délka {tenant}-{env-slug} musí zůstat ≤ 63 (K8s limit) — env-slug proto kratší limit (např. ≤ 20). Rezervovaná env-slug: talkide (default), plus reserved slug list (CLAUDE.md DO konvence).

4. Provisioning model — shared vs dedicated + konfigurace

Provisioning je idempotentní get-or-create per resource (konzistentní ADR-015 §8) a lazy (vzniká při prvním nasazení projektu do prostředí, ne při Create Environment — nebo eager pro DEDICATED, kde je provisioning těžký; finální granularita = Open Decision OD-3/OD-4).

EnvironmentProvisioner wrapper (interface + K8s impl + Noop) — stejný vzor jako ADR-014/ADR-015 (žádná výjimka z patternu). Provisioning failure → výjimka → @Transactional rollback (ADR-015 §11).

Konfigurace prostředí (config) drží minimálně: sizing (ResourceQuota třída / plán), DB tier (shared schema | dedicated cluster + velikost), storage tier. Granularita config v alfě = Open Decision OD-4 (přednastavené třídy vs. volné parametry) — nerozhoduje tento ADR.

5. Dvě billing vrstvy — per-environment attribution

• talkide-worker + Preview běží v „TalkIDE” prostředí → jejich infra cost je infra-postpaid náklad prostředí „TalkIDE” (transparentně na faktuře), NIKOLI AI prepaid. AI prepaid pokrývá jen Anthropic token inference.
• Každé další prostředí (TEST/PROD) je samostatná řádka na „Hosting/ Infrastructure” faktuře — user vidí cost per prostředí.
• Cost attribution = OpenCost aggregate=namespace (nativní, žádný intra-namespace label-split potřeba), protože jedno prostředí = jeden namespace (invariant sekce 3). Tím se rozpouští velká část be#125 (viz níže).

6. be#125 disposition (intra-namespace label-split)

Rozhodnutí: be#125 z velké části PADÁ, zůstává RESIDUUM jen pro přechodné období a unknown-workload safety net.

Zdůvodnění:

• be#125 / UC-10009 DP-4 V1 (label-aware C.2 aggregate=namespace,label: talkide.io/workload-class) řešilo problém „worker + build Joby + user-app pody jsou ve stejném tenant-{slug} ns, nelze je cost-rozlišit”.
• Pod Environment modelem (sekce 3 invariant) je každé prostředí vlastní namespace. talkide-worker + Preview žijí v „TalkIDE” ns; published prod app žije ve svém prod env ns. Cost je tedy přirozeně atribuovatelný aggregate=namespace (přesně to, co ADR-024 Consequences slibuje: „per-tenant izolace + billing attribution … bez heuristik”).
• Nově není potřeba intra-namespace label-split, protože „hosting vs ai-dev” hranice = hranice prostředí = hranice namespace. Worker compute není „misattribuovaný hosting” — je to legitimní infra-postpaid náklad prostředí „TalkIDE” (user ho vidí transparentně, platí ho jako infra postpaid, ne jako AI prepaid). Tím mizí samotný problém, který be#125 řešil.

Reziduum (zůstává):

1. Přechodné období — DOKUD je živý prod na starém tenant-{slug} modelu (jedno ns, preview+prod pohromadě) a DOKUD nepřistane ADR-024 worker do per-env ns, je aggregate=namespace na tenant-{slug} ns stále hrubé (smíchá preview+prod). Reziduální be#125 = dočasný label-split nebo namespace-split pouze pro období migrační Fáze 2–4 (viz migrační plán), než je per-environment ns invariant plně živý. Po dokončení migrace reziduum odpadá.
2. Unknown-workload safety net — i v cílovém stavu má smysl mít v C.2 explicitní handling „namespace, který se nemapuje na žádné environment” (orphan ns) → WARN + metrika + konzervativní non-charge (NEfakturovat neznámé na usera). To je jednoduchý guard, ne plný label-split.

Návrh textu pro aktualizaci GitLab issue be#125 — viz UC-10009 revize FEEDBACK a sekce „be#125 issue update” níže (PM přenese do GitLab, tento dokument GitLab nevolá).

Consequences

Pozitiva

• Jeden srozumitelný mentální model pro usera — „prostředí = kde to běží”; preview/prod přestává být skryté kouzlo builds.env.
• Billing attribution bez heuristik — jedno prostředí = jeden namespace = jedna cost-řádka; be#125 label-split z velké části odpadá.
• Aktivuje a zarámuje rozjeté workstreamy — ADR-024 worker-per-tenant-env a ADR-023 §5/§7 dostávají doménového ownera a user-facing důvod; nic se nesuperseeduje.
• Premium izolace jako produkt — ADR-023 §7 escape hatch (dedikovaný DB cluster) se stává user-volitelnou resource_mode=DEDICATED, ne ad-hoc ops.
• Decoupling AI ↔ infra zůstává čistý — AI prepaid (UC-10007) a infra postpaid (UC-10009) jsou dvě nezávislé vrstvy; default „TalkIDE” garantuje, že AI vývoj má vždy domov.

Rizika a omezení

1. Migrace živého produkčního usera. popelkam / todo-list.talkide.app běží na tenant-{slug} modelu. Migrace MUSÍ být fázovaná a non-disruptive (viz migrační plán) — entita Environment se zavádí nejdřív jako záznamová abstrakce nad existujícím stavem (default „TalkIDE” namapuje na současný tenant-{slug} ns) a teprve postupně se přepíná na per-env namespace.
2. Per-environment namespace = víc K8s objektů. ResourceQuota, RBAC, secret replikace (ADR-015 §4–6) per prostředí, ne per tenant. Connection budget invariant (ADR-023 ř.443) je per (db,user) — víc prostředí = víc per-app rolí. Hlídat monitoringem; škálování tenantů/prostředí = trigger pro vyšší DB tier (ne automatika).
3. DEDICATED provisioning je těžký a drahý. Dedikovaný DO Managed PG cluster per environment má reálnou $ a čas cenu. Alfa: omezit počet DEDICATED prostředí / gate plánem (Open Decision OD-3/OD-4).
4. Default env při neplacení infry — nesmazatelné „TalkIDE” nelze za neplacení smazat; co přesně se s ním stane (suspend Preview? grace? nikdy nesuspend?) je Open Decision OD-2, NErozhoduje tento ADR.
5. Naming / délkový limit — {tenant}-{env-slug} ≤ 63; env-slug validace + reserved list nutné před public alpha (analogie be#44).

Alternatives Considered

Implementation Notes

Vztah k existujícím ADR (explicitní)

Pořadí (foundation → navazující) — detail v migračním plánu

1. Foundation: entita environment + lazy default „TalkIDE” namapované na současný tenant-{slug} ns (čistě záznamová vrstva, žádná infra změna, žádný dopad na živého usera).
2. Billing per-environment napojení (UC-10009) — atribuce přes mapování ns→environment (zatím 1 ns „TalkIDE” = celý dnešní tenant-{slug}).
3. Create/Manage Environment UC (user vytváří USER_CREATED SHARED prostředí).
4. Per-environment namespace cut-over (aktivace ADR-023 §5 / ADR-024 substrátu).
5. DEDICATED resource_mode (ADR-023 §7 jako produkt).

Related issues a ADR

be#125 issue update (návrh textu pro PM — NEvoláno GitLab)

Re-scope (ADR-026 Environment first-class): Původní problém be#125 (worker

• build Joby + user-app pody nerozlišitelné v jednom tenant-{slug} ns → aggregate=namespace míchá hosting a ai-dev) z velké části zaniká. Pod ADR-026 je každé prostředí vlastní namespace; talkide-worker + Preview žijí v prostředí „TalkIDE” a jejich compute je legitimní infra-postpaid náklad toho prostředí (transparentně na faktuře), ne misattribuovaný hosting. aggregate=namespace → namespace→environment→tenant je nativní attribution bez label-splitu.

Zbývá (reziduum, zúžený scope):

1. Přechodné období — než per-environment ns invariant (ADR-026 migrace Fáze 4) plně přistane a než ADR-024 worker přejde do per-env ns, je aggregate=namespace na starém tenant-{slug} ns hrubé. Dočasný label-split NEBO namespace-split jen pro období migračních Fází 2–4. Po dokončení migrace tento bod odpadá (uzavřít).
2. Orphan-namespace safety net (trvalé, jednoduché) — C.2: namespace nemapující se na žádné environment → WARN + metrika + NEfakturovat usera (konzervativní non-charge). Není to label-split, je to guard.

Out of scope (přesunuto do ADR-026 / UC-10009 revize): plná per-environment billing attribution, DP-4 enforcement rozsah, dedicated resource_mode. Issue zúžit na reziduum výše; po migraci Fáze 4 zvážit close.