Spec: avax-apm — modulový program + sklad znovupoužitelných subaplikací (apc)¶

Status: v0.4 (2026-06-20) — apm na HOTOVÉM SEGMENT-skeletonu + content supply z app-legal (viz ## 0. v0.4): TEXTY místo formulí, multi-source (zákony/PDF/web/pluggable), vektorové vyhledávání nad zákony. v0.3 níže (vize + apc bundle + kompozice) platí dál — corpus/vektor vrstva ji krmí. Fork architektury apz-runner (legal-skeleton), jiný účel a model: apm = hlavní aplikace = modulový program, který se skládá z apc subaplikací — samostatných, znovupoužitelných stavebních bloků (kurzy, přednášky, testy, hry, …). apm Gitea repo = sklad + vývoj těchto komponent (s podobným zaměřením); tentýž apc jde použít ve více aplikacích. Druhý zdroj pravdy = avax-legal-apz.md (apz, compute runner) — apm forkuje jeho plumbing.

0. v0.4 (2026-06-20) — apm na SEGMENT-skeletonu + content supply z app-legal¶

Zásadní upřesnění směru (Michal). apm se NEpíše od nuly — staví se na hotovém SEGMENT-based apz-skeletonu (apz-runner: app-legal publikuje segmenty do avaxlegal/apz/segments/<seg>/ s temporal+checksum; runner syncuje; create_app picker; ověřeno E2E na apz-mzdy, golden 39570/7560/11314). apm forkuje TÉ plumbing, ale supply je TEXT/obsah, ne formule, z více zdrojů, s vektorovým vyhledáváním. §1–6 níže (v0.3) = apm vize + apc bundle + kompozice — platí dál; corpus/vektor vrstva (§0.2–0.4) je krmí.

0.1 Princip¶

„Segment" (apz) ⇒ „TÉMA" (apm). apz segment = compute doména (mzdy). apm téma = obsahová doména podle určení (kvalifikační požadavky, BOZP, GDPR, …).
apz: apl- formule → výpočet → číslo (trust = golden bit-exact). apm: TEXTY → korpus → kurzy/testy/obsah (trust = citace zdrojů + vendor review).
Reuse skeleton plumbing: sync (index→bundle→checksum→DB cache), temporal (valid_from/valid_to), M2M, gateway, CI auto-deploy, per-app schéma, Nastavení, paleta.
TRVALÝ PRINCIP — provenience (od 2026-06-22): každý apz vzorec/číselník/proměnná i apm law-text nese odkaz na zákon (§/odst./předpis + datum platnosti) a leží ve správné cestě (components/apl-*, segments/<seg>/, resp. topics/<topic>/). Law-grounded + auditovatelné; za každým číslem/textem stojí konkrétní zákon/verze.

0.2 Korpus = MULTI-SOURCE (vše konfigurovatelné v Nastavení app)¶

Apm app si v Nastavení skládá korpus z více zdrojů (přidatelné): 1. app-legal law-text-by-téma (NOVÁ role app-legal, primární zdroj) — per téma relevantní pasáže zákonů (e-Sbírka, [[reference_esbirka_api]]), temporálně verzované. Téma zadá apm admin (určení) → app-legal kuruje mapování pasáží (vektorově asistovaně, §0.4) + drží temporal: novela zákona → app-legal update pasáží → apm app syncuje nový text. S3 segment-model avaxlegal/apm/topics/<topic>/ (catalog + index + text bundly + temporal + checksum + vektor refy). 2. PDF / dokumenty — upload → doc-convert konektor = Qwen přes app-ai-helper (PDF/DOCX → strojově čitelný markdown/text, OCR pro skeny) → korpus. (Capability existuje — Qwen na GPU farmě.) 3. Web — fetch/snapshot URL → extrakce textu → korpus (URL + datum). 4. Pluggable — další typy zdrojů přidatelné (ebook, API feed, …); každý → normalizovaný text → korpus.

0.3 app-legal — NOVÝ DELIVERABLE (handoff) ⭐¶

„Speciální oddělení pro různé apm" = topic-keyed, temporálně spravovaný text supply + law-corpus vektor index. app-legal postaví: - Topic katalog (avaxlegal/apm/catalog.json) — registr témat (key, name, určení, status) + mapování na pasáže zákonů; témata zadává apm admin. - Per-téma law-text (avaxlegal/apm/topics/<topic>/index.json + bundly) — relevantní pasáže (§/odst. + plný text), temporal (valid_from/valid_to), checksum. Tvar = segment-model jako apz (konzistentní s avax-legal-skeleton.md §6.1). - Temporal management — novela / změna textu → re-publish pasáží tématu → apm app dostane nový text při syncu. (app-legal už temporal umí z e-Sbírka korpusu.) - Sdílený law-corpus VEKTOR INDEX (§0.4) + konektor legal-corpus (sync témat + sémantický search) pro apm runner.

0.4 Vektorové vyhledávání nad zákony¶

Embeddingy přes app-ai-helper ai-embed ([[reference_ai_helper_architecture]]) nad texty zákonů → sdílený law-corpus vektor index (app-legal spočítá jednou, víc apm appek queryuje; re-embed při novele).
Sémantický retrieval ai-rag-query: „najdi nejkorektnější/nejrelevantnější pasáže zákona pro téma/dotaz X".
Dvojí užití: (a) kurace témat — app-legal najde kandidátní pasáže pro nové téma sémanticky → zkuruje; (b) runtime grounding — apm app vytáhne relevantní zdroje + citace (anti-halucinace) při authoringu/dotazu.
apm app navíc indexuje své ingestnuté zdroje (PDF/web) → kombinovaný search (law-corpus app-legal + vlastní zdroje).

0.5 apm runner (na segment-skeletonu) + konektory¶

„segment" = téma; runner syncuje per-téma law-text (app-legal) + ingestnuté zdroje → corpus cache + vektor index.
Nastavení = správa zdrojů (legal témata + PDF uploady + web URL + pluggable).
Delivery = skládá/doručuje obsah (v0.3 apc/program model — kurzy/testy grounded v korpusu s citacemi + vektorově dohledanými zdroji).
Nové konektory: legal-corpus (app-legal: sync témat + vektor search), doc-convert (PDF/DOCX→text; nová platform capability).

0.6 Build plan¶

Fork segment-skeleton apz-runner → apm-runner (PAUSED fork už má jádro: runtime/{component,program,score}, sync/bundle, test_score 5/5).
Compute kernel → content delivery + corpus/vektor vrstva.
Platform: create_app app_kind=apm + topic-picker (jako segment-picker). ✅ SHIPPED 2026-06-30 — literál je apm (NE content; sjednoceno s apm-runner//apm/*/app_apm schématem). Template tools/avax-apm-app-template, backend is_apm větve, GET /admin/app-management/apm-catalog, launcher2 tlačítko „🎓 Nová apm aplikace".
app-legal postaví topic supply + vektor index + konektory (§0.3) — to je ta nová věc.
doc-convert capability (PDF→text) + web ingest + Nastavení správa zdrojů.

0.6.1 Create-app `kind=apm` — co dělá wizard (dev / ruční řešení) ✅ SHIPPED 2026-06-30¶

Admin „🎓 Nová apm aplikace" (launcher2 admin.py → _CreateAppV2Dialog(app_kind="apm") → POST /admin/app-management/create). Backend create_app při app_kind=="apm" (is_apm): - template tools/avax-apm-app-template (settings.APP_APM_TEMPLATE_PATH) → Gitea repo avax-apps/<slug>-app (push_template nahradí EDITME-slug/avax-app-EDITME + <slug>/<schema_slug>/<port> v backend-deploy.yml.example). - vždy backend (has_backend=True), health_path="/apm/health", port z range 8101-8199. - secrets: LEGAL_S3_* (sync z avaxlegal/apm/, stejný klíč jako apz) + APM_TOPIC (téma z picker, analogie APZ_SEGMENT) + auto-issued M2M (AVAX_M2M_CLIENT_*, scopes ai-chat/ai-rag-query/ai-rag-index/ai-speech — grounding zdroj A je veřejný, scope netřeba) + APPDIST_S3_. - téma-picker*: GET /admin/app-management/apm-catalog čte avaxlegal/apm/catalog.json → topics[] (prázdné dokud app-legal nepostaví supply → ruční zadání slug tématu).

Ruční řešení / gotchy (po prvním CI deployi): - gateway flip není automatický (obecný gap fullstack apps, ne apm): po prvním deployi POST :8000/admin/app-management/<slug>/auto-enable-gateway (localhost bypass) → gateway_enabled=t+is_public=t. - POST /apm/sync (admin JWT) = ruční krok (datová operace) — naplní apm_topics/apm_passages z avaxlegal/apm/ (do té doby prázdné — supply staví app-legal, §0.8). - UI = console.html servírovaná backendem na rootu (žádný web kontejner); launcher „Otevřít" → /apps/<slug>/.

0.7 app-legal handoff (copy-paste pro app-legal Clauda)¶

NOVÁ věc pro apm: postav „oddělení pro apm" = topic-keyed law-text supply na avaxlegal/apm/ (segment-model jako apz, ale TEXT): (1) catalog.json témat (kvalifikační požadavky, BOZP, GDPR…; témata zadává apm admin, ty mapuješ pasáže zákonů na ně); (2) per-téma topics/<topic>/ = plné texty pasáží zákonů, temporálně verzované (novela → update → app dostane nový text); (3) sdílený law-corpus vektor index (ai-embed nad korpusem) + konektor legal-corpus (sync + sémantický search „nejkorektnější texty pro téma X"). Vektor search používáš i ty na kuraci témat. Temporal/checksum/tvar = stejné jako apz segment supply (avax-legal-skeleton.md §6.1) — znáš to.

0.8 app-legal handoff — content supply kontrakt (k implementaci) ⭐¶

Detailní kontrakt, co app-legal staví pro apm. Tvar/temporal/checksum vocabulary = jako apz segment supply (avax-legal-skeleton.md §6.1).

S3 layout avaxlegal/apm/:

avaxlegal/apm/catalog.json                                  registr témat (create_app topic-picker)
avaxlegal/apm/topics/<topic>/index.json                     per-téma registr pasáží (temporal + checksum + vektor)
avaxlegal/apm/topics/<topic>/passages/<key>/v<seq>.json     law-text bundle (plný text pasáže + PROVENIENCE)

catalog.json — registr témat:

{ "topics": [
    { "key": "bozp",                          // = topic key, [a-z0-9-], téma zadá apm admin
      "name": "BOZP — bezpečnost a ochrana zdraví při práci",
      "purpose": "kvalifikační/školící obsah BOZP",         // určení
      "status": "active",                                   // draft | active
      "passages": 42, "index": "topics/bozp/index.json" } ] }

topics/<topic>/index.json — per-téma registr pasáží:

{ "topic": "bozp",
  "passages": {
    "zp-102-1": {                             // pasáž key
      "ref": { "predpis": "262/2006 Sb.", "par": "§102", "odst": "1" },  // PROVENIENCE (§0.1)
      "label_cs": "Povinnosti zaměstnavatele v prevenci rizik",
      "node_id": "…",                         // app-legal read_tree_nodes.id (kurace/read pointer); apm ukládá opaque (§0.8.1)
      "versions": [ { "version_seq": 1, "valid_from": "2024-01-01", "valid_to": null,
                      "checksum": "sha256:…", "key": "topics/bozp/passages/zp-102-1/v1.json" } ] } } }

passages/<key>/v<seq>.json — law-text bundle (immutable):

{ "passage_key": "zp-102-1", "version_seq": 1,
  "ref": { "predpis": "262/2006 Sb.", "par": "§102", "odst": "1", "eli": "…" },
  "valid_from": "2024-01-01", "valid_to": null,
  "text": "Zaměstnavatel je povinen … (plný text pasáže)",
  "checksum": "sha256:…" }

Co app-legal dělá (5 věcí): 1. Topic katalog + per-téma pasáže (S3 výše) — téma zadá apm admin (určení), app-legal zkuruje pasáže. 2. Temporal — novela → nová version_seq (valid_from=účinnost, předchozí valid_to) → re-publish → apm app syncuje nový text. (app-legal už temporal umí z e-Sbírka korpusu, [[reference_esbirka_api]].) 3. Sdílený law-corpus VEKTOR INDEX — ai-embed ([[reference_ai_helper_architecture]]) nad law korpusem; re-embed při novele. 4. Konektor legal-corpus — legal-corpus.search (sémantický search: query → nejrelevantnější pasáže + skóre + provenience) · legal-corpus.read (raw text by ref). 5. Provenience — KAŽDÁ pasáž nese ref (§/odst./předpis + valid_from/valid_to). Bez ní = nekompletní (TRVALÝ PRINCIP, §0.1).

Curation flow: apm admin zadá téma → catalog entry (status:draft) → app-legal najde kandidátní pasáže legal-corpus.search (vektorově) → zkuruje → publish topics/<topic>/ (status:active). Temporal pak app-legal drží průběžně.

Creds: stejný LEGAL_S3 klíč jako apz (avaxlegal bucket, prefix apm/) — runner ho dostane z create_app inject, app-legal píše svým avaxlegal klíčem. (Pokud Michal udělá dedikovaný apm user/bucket, vyměníme prefix/endpoint.)

0.8.1 LOCKED — boundary + §8 sladění s app-legal (2026-06-22) 🔒¶

Sladěno s app-legal docs/spec/avax-legal-apm-supply.md (d3886d8) + handoff HANDOFF_APM_VECTOR_GROUNDING_JC.md (f61c455). Spec-first §3–4 zamčeno PŘED stavbou (jako apz).

BOUNDARY (potvrzeno): apm = konzument dvou existujících vektorových strojů, NESTAVÍ třetí. - A) Zákony → app-legal legal-corpus.search (POST /apps/app-legal/legal/search/semantic {query,k,eli?} → §§ + provenience + score). LIVE (app-legal 0.4.0, gated backfill embeddingů). - B) Vlastní zdroje (PDF/web/knihy) → app-ai-helper RAG (ai-rag-index/ai-rag-query). Embedding produkce obou = app-ai-helper ai-embed. - apm grounding (#18) = orchestrace A+B → sloučený kontext → LLM s citacemi (§0.4). apm NEre-embeduje korpus zákonů (app-legal 1×, sdílené, re-embed při novele), indexuje JEN své ingestnuté zdroje (#19) přes ai-rag.

Kontrakt §3–4 alignment (2 položky): 1. index.json pointer = node_id (app-legal read_tree_nodes.id), NE vector_id. apm-runner ukládá opaque (sloupec apm_passages.vector_id), používá jen pro korelaci / legal-corpus.read, neinterpretuje. 2. passage summary (volitelný laický přepis) — apm-runner uloží pro grounding kontext; chybí → OK.

§8 rozhodnutí (JC platforma): 1. legal-corpus.read = by-ref (eli+path+volitelný at), shodně se search outputem. apm-runner ho NEpotřebuje pro nasyncované topic pasáže (text je v S3 bundlech → DB cache); read = jen runtime grounding nad §§ MIMO topic supply → nižší priorita (search + S3 bundly pokrývají jádro). Stavět read až grounding bude potřebovat full-text non-topic §§. 2. node_id pointer: app-legal produkuje, apm ukládá opaque (viz výše). 3. Creds/bucket: avaxlegal prefix apm/ (jako apz) — apm config to už defaultuje (legal_s3_prefix="apm") + create_app injektuje LEGAL_S3. Žádný dedikovaný bucket. 4. Témata: app-legal vlastní catalog.json (apm-runner je read-only na avaxlegal → NEpíše). Určení předá apm → app-legal jako seznam (později konektor apm→app-legal write, až produktizujeme topic-picker). apm-runner čte catalog.json pro topic-picker (jako apz segment-picker). 5. Review gate: dvě brány — app-legal review pasáží (status:active v catalogu) PŘED publishem; apm review apc kompozice (§5). apm trustuje active témata.

Prereq stav: (a) apm-runner STOJÍ ✅ (avax-app-apm-vzor :8115, deployed 2026-06-22). (b) téma ZADÁNO ✅ (2026-06-22):

// topic list předaný app-legalu pro #23 kuraci:
{ "key": "bozp",
  "name": "BOZP — bezpečnost a ochrana zdraví při práci",
  "purpose": "kvalifikační/školící obsah BOZP",     // určení
  "predpisy_hint": ["262/2006 Sb. §101–108 (zákoník práce, prevence rizik)", "309/2006 Sb."] }

→ app-legal teď zkuruje pasáže (legal-corpus.search vektorově) + publikuje avaxlegal/apm/topics/bozp/ (status:active) + dostaví legal-corpus.read + topic supply publisher. Pak E2E POST /apm/sync → grounding (#18).

1. Vize — modulový program + component sklad¶

apm dělá tři věci (proto „fork, který funguje jinak"):

VÝVOJ — in-app Claude autoruje apc subaplikace (kurz/test/hra/…) grounded ve zdrojích (knihy, web, zákony), dev-time, s citacemi; vendor je reviewuje.
SKLAD — apc jsou verzované immutable komponenty uvnitř jednoho apm Gitea repa + publikované do sdíleného S3 → katalog znovupoužitelných modulů s podobným zaměřením.
KOMPOZICE — modulový program (apm) skládá apc do soudržné aplikace (kurikulum, školící cesta, multi-modul); tentýž apc lze použít ve více programech i aplikacích (develop once, reuse everywhere).

Odlišení od apz:

	apz (compute)	apm (modulový program / sklad)
Komponenta	`apl-` law-based formule (z app-legal)	`apc-` subaplikace (obsah + interaktivita + scoring)
Původ komponent	externí (app-legal compiler → `avaxlegal/apz/`)	in-house: Claude autoruje uvnitř apm repa
Co je „program"	topologie výpočtu → číselný output	kompozice `apc` → složená aplikace
Reuse	subprogram napříč programy	`apc` napříč programy I aplikacemi
Sklad	—	apm repo = sklad + vývoj komponent
Trust	golden bit-exact	citace zdrojů + vendor review (scoring = deterministický)

Forkuje se plumbing (runner kostra, sync index→bundle→checksum→DBStore, M2M, gateway, CI, web, connector, extensions). Mění se jádro: compute engine → delivery + scoring + kompozice; externí supply → in-house authoring + sklad + RAG grounding.

2. Naming (potvrzeno Michalem)¶

app / hlavní aplikace = apm-<slug> (apm-akademie) — modulový program; sibling repo v C:\avaxis\apps\.
subaplikace / komponenta = apc-<name> (apc-zakonik-prace-kurz, apc-gdpr-test) — verzovaná uvnitř apm repa, znovupoužitelná napříč apps.
generický skeleton = apm-runner (fork apz-runner); instance apm-<slug> (create_app app_kind=apm, template tools/avax-apm-app-template).
kind apc = course | lecture | test | game | … (rozšiřitelné).

3. Ekosystém — úložiště (klíčový rozdíl od apz)¶

Gitea apm-<slug> = SKLAD + VÝVOJ (jeden repo, NE repo-per-komponenta):

apm-<slug>/
  components/apc-<name>/v<seq>/   ← subaplikace, verzované UVNITŘ repa
  programs/<name>/                ← modulové programy (kompozice apc)
  sources/                        ← podklady (knihy/PDF/web snapshoty) k authoringu
  .claude/ (memory)               ← in-app Claude (autorská role)
  backend/ web/ .gitea/           ← runner fork (kód)

Gitea = SoT pro vývoj + verzování apc i programů. B paralela: i v apz repu se takto odverzují subprogramy.

S3 supply avax-apm/ (jeden bucket, prefixy) — components/apc-<key>/v<seq>/ (sklad apc) · programs/<key>/ (kompozice) · sources/<slug>/ (zdroje). CI publikuje immutable apc + programy → sdílený katalog, víc apps konzumuje (reuse). Runner JEN čte; components/programs sdílené readable, sources per-app private (řízeno prefixem).
Source corpus avax-apm/sources/<slug>/ — ingestované zdroje (knihy, web, zákony) → RAG index (app-ai-helper) → grounding + runtime citace.
User-tenant (DB tenant schema + S3) — progress, pokusy, skóre, certifikáty (per-firma).

4. Zdroje (sources) — knihy + web + zákony¶

Zákony — texty z app-legal/app-zakony (paragrafy, e-Sbírka korpus — [[reference_esbirka_api]]), ne formule, přes connector legal-corpus.read (read-only).
Knihy — PDF/ebook → parse → index (učebnice, odborné publikace).
Web — fetch/snapshot stránek (výklady, guidance) s URL+datem.
Stažené dokumenty — obecné (DOCX/HTML/…).

→ Source corpus per app, RAG-indexovaný (ai-embed + ai-rag-*, [[reference_ai_helper_architecture]]) → Claude autoruje grounded + runtime citace.

5. Authoring pipeline (dev-time, vendor review)¶

In-app Claude (vlastní memory, autorská role): 1. Brief (vendor/člověk): „vytvoř kurz o ZP", „test z GDPR", „hra o…". 2. Ingest sources (§4) → corpus → RAG. 3. Autoring (ai-chat + ai-rag nad korpusem): napíše apc grounded — každá pasáž → citace zdroje. 4. Vendor review (potvrzeno: review dělá vendor) — review_status: approved až po kontrole; anti-halucinace (žádný vymyšlený zákon). 5. Publish — immutable bundle → version uvnitř apm repa + CI → S3 sklad (§3.2) + index.json.

Dev-time (potvrzeno) — ne runtime generování. (Runtime AI dotaz nad korpusem = volitelné, later.)
app-ai-helper = autorský + grounding engine (apm = konzument; GPU farma neřeší).

6. `apc` subaplikace — bundle formát¶

{
  "component_format": 1,
  "component_key": "apc-zakonik-prace-kurz",
  "kind": "course",                     // course|lecture|test|game|…
  "version_seq": 1,
  "valid_from": "2024-01-01", "valid_to": null,
  "label_cs": "Kurz: Zákoník práce — základy",
  "focus": "pracovni-pravo",            // „podobné zaměření" → skupina ve skladu
  "content": { /* kind-specific */ },
  "sources": [                          // GROUNDING — povinné u faktických tvrzení
    {"type":"law","ref":"262/2006/§52","citation":"…","source_version":"2024-01"},
    {"type":"book","ref":"sources/ucebnice-zp.pdf#p120","citation":"…"},
    {"type":"web","ref":"https://…","fetched_at":"2026-06-18"} ],
  "assets": [ {"key":"obr1","s3_ref":"…","mime":"image/png"} ],
  "runtime": { /* scoring (test), pravidla (game), navigace (course) */ },
  "authored_by": "claude", "reviewed_by": "<vendor>", "review_status": "approved",
  "checksum": "sha256:…"               // kanonický algo == apz (reuse sync/bundle.py)
}

2 úrovně (potvrzeno, jako apz): program skládá apc; apc je plochá subaplikace — neskládá jiné apc (hloubku řeší obsah uvnitř, ne nested moduly).

kind-specific content: course (modules[] lekce+citace+navigace), lecture (sections[]/slides + TTS), test (questions[] typ/options/correct/feedback/citation + scoring), game (game_type/config/rules/scoring).

7. Modulový program — kompozice `apc` (jádro apm)¶

Program = manifest, který skládá apc do aplikace (paralela apz program = subprogramy):

{
  "program_format": 1,
  "program_key": "akademie_pracovni_pravo",
  "label_cs": "Akademie: Pracovní právo",
  "modules": [                          // pořadí/flow apc subaplikací
    {"id":"m1","component":"apc-zakonik-prace-kurz","version":"latest"},
    {"id":"m2","component":"apc-gdpr-test","version":1},
    {"id":"m3","component":"apc-ergonomie-hra"} ],
  "flow": { "type":"sequence|free|gated", "edges":[{"from":"m1","to":"m2"}] },
  "presentation": { "dashboard": {…}, "certificate": {…} },
  "checksum": "sha256:…"
}

modules[] referencují apc key+version → reuse: tentýž apc v N programech/aplikacích.
flow = navigace/gating (sekvence kurikula, volný výběr, podmíněné odemčení).
Program i apc verzované uvnitř apm repa; publikované do skladu.

8. Reuse napříč aplikacemi (proč „sklad")¶

apc identifikováno key+version → referencovatelné víc programy I jinými apps.
Cross-app = KOPIE s verzí + update (potvrzeno): konzumující app si apc zkopíruje do svého skladu pinnuté na verzi (jako package dependency), ne runtime embed. Zdroj vydá novou verzi → update flow (consumer vědomě povýší). Izolace + reprodukovatelnost; zdroj se mění bez rozbití konzumenta.
Connector PROVIDES content.module: katalog skladu + výdej apc bundlu (key+version) ke kopii; signál o nové verzi → update.
Sklad = katalog modulů s podobným zaměřením (focus) → kurátorská znovupoužitelnost.

9. Sync model (reuse apz)¶

index.json (registr apc + programů + verzí) → stáhni apc/<key>/v<seq>/bundle.json + programs/<key>.json → ověř checksum → upsert DB cache. Immutable, read-only. = apz/sync/s3.py mechanika.

10. Runtime / delivery + scoring¶

course: player (moduly, progress, citace inline). lecture: viewer (slides/text/TTS ai-speech). test: present → submit → deterministické scoring (golden-like) → skóre+feedback+citace. game: session state, pravidla, skóre.
program: skládá moduly do dashboardu (flow, progress napříč apc, certifikát).
„Resolved" apm = session state (program-in-progress / test-attempt+score / game-session) → audit snapshot.

11. API kontrakt (paralela apz §8)¶

GET /apm/programs · /apm/programs/{key} (kompozice+flow) · GET /apm/components (sklad katalog) · GET /apm/components/{key}/manifest · POST /apm/{program|component}/{key}/start (session) · POST /…/submit (test/game → skóre+citace) · GET /apm/sessions · POST /apm/sync (admin). Auth jako apz.

12. DB schéma (per-app schema `apm`)¶

apm_components (cache apc) · apm_programs (cache kompozic) · apm_sources (corpus registr) · apm_sessions (progress/skóre — per-tenant). Multi-tenancy: apc/programy = sdílená knihovna (immutable); progress/skóre = per-firma ([[reference_avax_tenancy_capability]]).

13. Determinism / grounding boundary¶

apm Claude dodá obsah apc; trust = citace zdrojů + vendor review (ne golden). Scoring testu/hry = deterministický (golden-like, reprodukovatelný).
Hranice „nehalucinuj": obsah konzumuje ze zdrojů (cituje), vendor review GATE před publishem.

14. In-app Claude (apm authoring Claude)¶

Vlastní memory dir, autorská role (vývoj apc ze zdrojů, ne app-modeling). Workflow §5. Smí app-ai-helper; nepíše AI infra. Seed: ecosystem brief + zdroje + focus + review pravidla.

15. Web¶

Katalog skladu → program dashboard (moduly, flow, progress, certifikát) → course player / test runner / lecture viewer / game host. Data-driven z /manifest; scoring server-side.

16. GATE (PoC — návrh)¶

Claude ingestuje zdroje (zákon ZP/GDPR + 1 kniha PDF) → corpus + RAG.
Autoruje 2 apc grounded: apc-gdpr-test + apc-zakonik-prace-kurz → vendor review → publish do skladu.
Modulový program akademie_pracovni_pravo složí oba apc → /apm/sync → dashboard + course player + submit testu = deterministické skóre + citace.
Reuse check: apc-gdpr-test referencovaný druhým programem (dokázat cross-program reuse).

17. Reuse z apz vs nové¶

Vrstva	apz	apm
Runner kostra / sync / DBStore / M2M / gateway / CI / web	✅	reuse
Kompozice (program = moduly + flow)	program=subprogramy	reuse vzoru (apc moduly)
Jádro	engine/formula/temporal	delivery + scoring + kompozice
Původ komponent	app-legal (externí)	in-house authoring v repu (sklad)
Trust	golden	citace + vendor review
Nové	—	source ingest + RAG + authoring + sklad + cross-app reuse

18. Vyřešené (tento turn) + zbývající otázky¶

Zamčeno: apm=hlavní app / apc=subaplikace · dev-time authoring · review=vendor · zdroje=knihy/web/zákony · 1 Gitea repo verzuje apc uvnitř · apm=modulový program skládající apc · 2 úrovně (apc neskládá apc) · cross-app reuse = kopie s verzí + update · create_app app_kind=apm (fork apm-runner, template tools/avax-apm-app-template).

Dořešeno (tento turn): 1. Úložiště = jeden bucket avax-apm/, prefixy components/ · programs/ · sources/<slug>/ (warehouse sdílený readable, sources per-app private). 2. Update policy = consumer pinuje přesnou version; nová verze ve skladu → signál (connector event) → ruční povýšení (explicitní, reprodukovatelné; žádný auto-update). 3. Focus = jeden apm app = jeden focus (tematický sklad, např. apm-pravni-akademie); víc focusů → víc apm apps; focus pole taguje apc uvnitř skladu.

→ Spec ~95 %, ready to lock. Po locku: fork apm-runner (§19).

19. Sekvence¶

Lock spec (~95 % s Michalem, [[feedback_spec_first_before_code]]) →
Fork apz-runner → apm-runner (kostra + sync + DBStore + web + CI; jádro = stub content runtime + kompozice) →
Source ingest + RAG + authoring memory (in-app Claude) →
GATE PoC (§16: 2 apc + 1 modulový program + reuse) →
Provision první apm-<slug> + in-app Claude.

Spec-first: žádný kód, dokud spec nesedí na ~95 %.