Co to znamená
majordomus generate zapisuje typovaný strom. Každý soubor v něm deklaruje čtyři věci: dokument, který promítá, kódování, v němž je zapsán (json, yaml, markdown nebo text, podle vlastní přípony), schéma, které jeho obsah splňuje tam, kde dokument má kontrakt, a zdroj, z něhož byl odvozen. Každý soubor nese hlavičku provenience ve tvaru, který jeho kódování dovoluje, takže člověk, který ho otevře, zjistí, že jde o cache, dřív než ho upraví.
Dokument je jedna hodnota. docs/generated/registry.json a docs/generated/registry.yaml jsou dvě její vykreslení; docs/generated/benchmarks.md, .json a .yaml jsou tři. Nemohou se neshodnout, protože existuje jeden výpočet a několik kodérů — tentýž tvar, jaký tento repozitář vyžaduje od každého jiného rozhraní.
Rejstřík celé sady je docs/generated/artifacts.{json,yaml,md} a je generovaný. Nikde nic neuchovává seznam toho, co je generované: tím seznamem je plán.
Princip
generate::Artifact nese deklaraci a generate::Document nese hodnotu; Document::artifacts vykreslí hodnotu do každého kódování, v němž je dokument commitnut. Kontrakty žijí pod share/schemas/generated/, jedno schéma JSON na dokument, přiřazené mu podle const jeho člena schema — objevování schémat druhů nerekurzuje, takže nic z toho nelze číst jako schéma druhu objektu.
generate::verify zkontroluje celý plán dřív, než se zapíše nebo porovná jediný bajt: deklarované kódování proti příponě, hlavičku proti kódování, dokument proti jeho zveřejněnému kontraktu a manifest proti plánu. generate i generate --check ji spouštějí, takže se nikdy nevytvoří napůl typovaný strom ani se nehlásí jako synchronizovaný.
Tři vlastní kódování manifestu nenesou hash — dokument, který by hashoval sám sebe, by neměl pevný bod — a --check je místo toho porovnává bajt po bajtu, což je silnější tvrzení.
Jak to vidět
apps/majordomus-cli/target/debug/majordomus generate --check # names each file with its schema, then: in sync
sed -n '1,6p' docs/generated/registry.yaml # the banner, then schema/generated/generator
printf '\n' >> docs/generated/registry.yaml
apps/majordomus-cli/target/debug/majordomus generate --check # exit 10: docs/generated/registry.yaml (differs)
apps/majordomus-cli/target/debug/majordomus generate registry # both encodings restored, from one value
curl -s localhost:8741/api/v1/artifacts | jq '.tallies' # the same manifest, reconciled with the treedocs/generated/artifacts.md je index pro čtenáře; /cockpit/artifacts a /registry/artifacts/ webu jsou týž index jako stránka.
Co nepokrývá
Bootstrapy providerů (AGENTS.md, CLAUDE.md) nesou místo tohoto bannera razítko majordomus update politiky, ze které byly vykresleny: projekce regionu vlastní část souboru, který nenapsala, a hlavička na jeho začátku by byla tvrzením nad textem, který generátor nevlastní. Kopie manifestu na webu nese deklarace bez velikostí a hashů, protože dva subjekty manifestu zapisuje pozdější fáze scripts/derive než ta, která kopii vytváří; hashe se místo toho odpovídají živě. A schéma zde fixuje nejvyšší úroveň a tvar každé položky, místo aby opakovalo typy v Rustu, takže přidání pole do deskriptoru není změnou schématu, zatímco jeho odebrání ano.
Proč existuje
Generátor věděl věci o svém výstupu, které výstup nenesl: některé soubory uváděly, že jsou generované, a jiné ne, jeden jmenoval schéma, které splňuje, a další ne, matice měření výkonu existovala pro čtenáře, ale ne pro program, nic nebylo napsáno v YAML a žádný soubor nikde neříkal, čím generovaná sada byla. Každé z toho je táž vada. project.generated-artifacts-are-typed@1 je pravidlo; apps/majordomus-cli/tests/generated_documents.rs dokazuje každou klauzuli nad skutečným plánem a dokazuje, že každá klauzule, porušená, je odmítnuta; test/cases/52_generated_artifact_typing.sh to dokazuje o commitnutém stromu a čte každé .yaml parserem YAML, který tento repozitář nevlastní.