Co to znamená
Vše, co tento repozitář vystavuje přes HTTP, je jeden rozlišený objekt: identita, mount, druh, kategorie, viditelnost, producent, který jej vytvořil, a provenience každé z těchto hodnot. Trasy, na které spustitelný soubor odpovídá sám, pocházejí z deklarací capability!, které už existují a už jsou promítnuty do CLI, MCP a OpenAPI. Generovaný adresář — testovací zpráva, zpráva z měření výkonu, build dokumentace — se deklaruje vedle vlastního výstupu, ne v seznamu někde jinde. Web aplikace se čte z konfigurace generátoru webu. Neexistuje centrální manifest povrchů a rozlišený manifest zapsaný pro diagnostiku je zahoditelný: nic jej nečte jako pravdu, kterou by nešlo přepočítat.
Všichni konzumenti čtou toto jedno vyřešení. Router dispatchuje tak, že se ptá, který povrch vlastní cestu požadavku, místo aby povrchy jmenoval ve větvích match. Úvodní stránka na / se vykresluje z topologie, seskupená podle kategorie, kterou každý povrch deklaruje. /api/v1/web/surfaces odpovídá stejnou hodnotu programu. Publikace sestavuje povrchy, které přispívají soubory. Tato stránka a její tabulky jsou generovány z commitnuté projekce. Povrch, který se objeví v jednom z nich a v jiném ne, je drift, který pravidlo zakazuje, a ručně psaná tabulka tras — v Rustu, v šabloně, v Markdownu, v JSON, YAML či TOML — je vada, ať aktuálně souhlasí, či ne.
Princip
apps/majordomus-cli/src/web/model.rs drží slovník: SurfaceKind je behaviorální (StaticDirectory, NativeRoute, Redirect), ne nominální, takže se report testu a report měření výkonu liší daty, ne typem. Mount normalizuje a odmítá, nikoli opravuje — žádné .., žádný prázdný segment, žádný query, žádné zpětné lomítko — a Topology::new řadí povrchy podle hloubky, takže přednost rout se počítá, a nezáleží na tom, kdo vložil poslední. discover.rs vyhodnocuje ze tří zdrojů odvození; validate.rs drží invarianty, kontrolované po světech, aby nasazovací a runtime povrch mohly sdílet mount, na kterém nikdy nemohou odpovídat oba; compose.rs sestavuje publikovatelný strom. http/surfaces.rs zužuje topologii na běžící proces a váže handler ke každému nativnímu povrchu, přičemž odmítá už při konstrukci — ne při požadavku — když se dva povrchy střetnou nebo nativní povrch nemá za sebou kód. Surface::served_by vypouští povrch, jehož runtime funkci tento build nebo vyvolání nemá, takže registr popisuje efektivní proces, ne maximální.
majordomus generate zapíše docs/generated/web.json a generate --check jej udržuje aktuální. scripts/generate-site-data čte tento commitnutý dokument, odmítne ten, který není majordomus/web-topology/v1 nebo postrádá povinné pole, a promítá jej do site/data/generated/web.json a do stránky, kterou čteš.
Jak to vidět
majordomus web list # the resolved topology, route-precedence order
majordomus web explain swagger # where each of that surface's values came from
majordomus web validate # the invariants, per world
majordomus generate --check # docs/generated/web.json is current
curl -s localhost:PORT/api/v1/web/surfaces | jq '.surfaces[].mount'
bash test/run.sh 89_web_surface # the page and the index describe the same setCo nepokrývá
built_from — revize, ze které byl statický artefakt sestaven — v commitnuté projekci záměrně chybí. Je to fakt artefaktů jednoho checkoutu a jeho commitnutí by způsobilo, že by každý klon hlásil drift pod generate --check. Je přítomna v živé odpovědi a v surface.json, které producent zapisuje.
Pravidlo omezuje, kde se povrch deklaruje a co ho smí číst; neomezuje, co povrch poskytuje. Producent zůstává svobodný zapisovat do vlastního adresáře, co chce.
Proč existuje
Tvar rozhodlo to, že dva další povrchy přišly najednou. Přidány tak, jak ty dřívější, by každý stál trasu v routeru, výstupní cestu ve skriptu, třídu cest v modelu kontrol, krok kopírování v publikaci, řádek v dokumentační tabulce a zmínku v nasazovacím workflow — šest registrací pro jeden adresář HTML a sedmý povrch by stál totéž znovu. Registraci, kterou člověk zapomene, nikdy není ta v routeru, protože rozbitá trasa se pozná za minutu; je to ta v dokumentaci, protože reference tras, která lže, se pozná až poté, co jí někdo uvěřil. ADR 0013 zaznamenává rozhodnutí a co zamítlo.