Jedna kanonická deklarace, skládané moduly, odvozené projekce a výkon jako důkaz

4. Jedna kanonická deklarace, složené moduly, odvozené projekce a výkon jako důkaz

Rozšiřuje ADR 2 a ADR 3.

Kontext

ADR 2 učinilo z každého rozhraní Rust executable projekci jednoho registru schopností. Dvě věci se stále psaly ručně nebo vůbec: registr byl jeden plochý seznam všech executables a nic se neměřilo. Zadání operátora bylo jasné: přispěvatel, který přidá jednu schopnost, upraví jednu kanonickou deklaraci a nic jiného, žádné rozhraní nesmí nést druhou kopii faktu, každá externě volatelná operace musí být měřena se jmenovatelem, který nikdo nepíše, požadavek nikdy nesmí znovu sestavovat kanonický stav, cache musí být prokázány jako ekvivalentní a každé tvrzení o rychlosti musí mít čísla. MCP povrch byl změřen dříve než cokoli z toho: capabilities list trvalo 166 ms na volání přes MCP a 57 ms přes HTTP na tomto repozitáři, protože výpis dodával stejné schéma objektového pohledu pro každý ze dvou set deklarativních resources, resources/list trvalo 15 ms, protože při každém požadavku procházelo registr, a studený majordomus mcp potřeboval čtvrt sekundy na odpověď na svůj první tools/list.

Rozhodnutí

• Jedna deklarace. capability! je celá deklarace spustitelné věci: id, volitelný druh (query, nebo command pro takovou, která mění paměť tohoto procesu), titul, popis, typovaný vstup a výstup, stabilita, expozice, tagy, volitelná politika cache, volitelná politika měření výkonu, handler. Typ vstupu implementuje BenchmarkCases, takže schopnost bez vstupu pro měření výkonu se nezkompiluje. Schémata se odvozují z typů; názvy MCP, operace OpenAPI, Swagger UI, příkazová řádka, cíle měření výkonu, chování cache a generované dokumenty jsou odvozeny. Nic se nepíše podruhé.
• Moduly skládají schopnosti; kořen skládá moduly. module! sestaví ModuleDescriptor (id, název, popis, stabilita, spustitelné soubory) a vtiskne své id na každou schopnost; compose_modules![repository, objects, capabilities, peers, perf] v builtin/mod.rs je jediná kořenová kompozice a schopnost přidaná uvnitř modulu nevyžaduje úpravu kořene. Registr odmítne schopnost složenou v jiném modulu než ve jmenném prostoru jejího id, modul složený dvakrát, neplatné id modulu, politiku cache, která nic nedrží, cachovaný příkaz a politiku měření výkonu, která odporuje druhu. Deklarativní objekty se připojují ke stejnému registru se svým druhem jako modulem; nic nemá druhý registr.
• Makra generují hodnoty, ne registry. capability!, module! a compose_modules! jsou macro_rules!, která budují prosté hodnoty předávané výslovně staviteli registru v app.rs. Žádné procedurální makro, žádný globální měnitelný registr, žádný link-time inventář, žádný build skript skenující zdroje.
• Jeden executor. Každé volání každým transportem, příkazovou řádkou a runnery měření výkonu prochází přes CapabilityExecutor::execute (Context::execute): vyhledání v registru, čítače, cache, kterou deskriptor žádá, handler. Transporty převádějí protokol a nevlastní nic jiného. Surové registry.dispatch existuje jen pro executor.
• Cache je politika na deskriptoru. CachePolicy::Process { max_entries, ttl } drží výsledky v paměti procesu, klíčované kanonickým id, vstupem v kanonické podobě (klíče objektů seřazené na každé úrovni) a otiskem registru (sha-256 otisku indexu, sám nad cestou a obsahem každého objektu, a každého deskriptoru). Chyby se nikdy neukládají do cache; příkazy se nikdy neukládají; nic se neperzistuje. Dvě schopnosti ji deklarují, protože to ukázalo měření: objects.search a capabilities.list.
• Výkon se počítá, pak měří. perf::COUNTERS počítá práci, která se musí stát jednou (skeny repozitáře, sestavení indexu a registru, generování schémat, sestavení projekce MCP, sestavení OpenAPI, sestavení HTTP routeru), a práci, která se děje při každém volání (exekuce, vyvolání handlerů, zásahy cache, minutí, vyřazení), s časováním fází na monotónních hodinách; perf.counters na ně odpovídá přes každý transport. Strukturální testy pošlou stovky požadavků skutečnými transporty a vyžadují, aby se startovní čítače nezměnily. Výpisy nástrojů a zdrojů MCP se připravují jednou; capabilities.list odpovídá souhrny a plný deskriptor je vzdálen jedno describe; schéma pohledu na objekt se odvozuje jednou na proces.
• Každá operace je cílem měření. BenchmarkProjection odvozuje z registru proti repozitáři jeden cíl na každý požadovaný program, na každý přenos, na kterém je vystaven, na každý případ jeho vstupního typu, plus vlastní operace přenosů deklarované jednou jako SystemTarget. Pokrytí je covered / required s generovaným jmenovatelem; výjimky jsou typované, hlášené a nikdy se nezapočítávají; capabilities validate selže na chybějícím požadavku. Runnery měří čas přímo přes executor (za studena a za tepla u cachované schopnosti), přes skutečný loopback socket se vstupem navázaným tak, jak jej váže trasa, a přes skutečný potomek majordomus mcp --standalone s novým procesem na vzorek u cíle za studena na úrovni procesu. Výsledky jsou verzovaný dokument s commitem, špinavým stavem, profilem buildu, platformou a otiskem registru; lokální běhy jdou pod .ai/local/benchmarks/, přijatá základní linie je jeden sledovaný soubor na platformu pod .ai/repo/benchmarks/rust/, povyšovaný jen příkazem bench baseline update, a politika regrese jsou data vedle ní. Zastaralá položka základní linie se hlásí jménem a nikdy se nepřipojí k přejmenovanému cíli.
• Generované artefakty jsou odvozené a sladěné. docs/generated/openapi.json, referenční index a jedna stránka na každý spustitelný modul, benchmarks.md a registry.json zapisuje majordomus generate a generate --check je porovnává bajt po bajtu; každý soubor říká, že je generovaný, a jmenuje svůj zdroj; žádné časové razítko.
• Garance založené na vlastnostech. Strategie proptest se odvozují pro každý spustitelný soubor z jeho případů měření výkonu a polí jeho vstupního typu; jedna strategie napájí ekvivalenci cache, normalizaci klíče, ekvivalenci transportu, determinismus projekce a vlastnosti detekce duplicit.

Vůči seznamu „Intentionally Absent“, bod po bodu

Invarianty

1. Schopnost je jeden blok capability!; změna jejího id, titulu, popisu, vstupu, výstupu, vystavení, cache nebo politiky měření změní každou projekci a žádný jiný soubor (tests/projections.rs, tests/bench.rs).
2. Kořen skládá moduly a jen moduly (tests/registry.rs).
3. Každý spustitelný je cílem měření výkonu přímo i na každém vystaveném transportu, s případy, které poskytuje jeho vstupní typ; pokrytí je úplné, nebo validate selže (tests/bench.rs, capabilities validate).
4. Po spuštění žádný požadavek neprohledává repozitář, nesestavuje index ani registr, neodvozuje schéma ani nesestavuje projekci (tests/hot_path.rs).
5. Schopnost s cache odpovídá toutéž hodnotou bez cache, studeně i teple; zásah nespustí žádnou obslužnou funkci; chyby a příkazy se nikdy necachují; mez drží; pořadí klíčů je nepodstatné; otisk odděluje stavy repozitáře (tests/executor.rs, tests/properties.rs).
6. Každý generovaný artefakt je deterministický a sladěný (generate --check).
7. Základní hodnota se porovnává jen na své vlastní platformě, podle politiky, která je daty, a nikdy se tiše nepřipojí k přejmenovanému cíli.

Zamítnuté alternativy

• Procedurální atributová makra (#[majordomus::capability(...)]). Přinesla by kratší zápis za cenu druhého cratu, testovací harnessu pro kompilaci a generovaného kódu, který nikdo nečte; deklarace macro_rules! už každý fakt drží jednou a bez případu měření se nezkompiluje. Vratné: kontraktem je deskriptor, který makro staví, ne syntaxe makra.
• Registrace v době linkování (inventory, linkme) a build skripty skenující src/: skladba by přestala být čitelná v jednom souboru; zamítnuto i zadáním samotného operátora.
• Booleovské read_only místo druhu command: tři projekce by ho každá konzultovaly; druh nese sémantiku jednou (ADR 3).
• Cachovat každou schopnost ve výchozím stavu. Většina handlerů odpovídá v mikrosekundách z neměnného indexu; cache tam je druhá kopie ničeho. Dvě cachované byly nejdřív změřeny.
• Trvalá cache výsledků. Invalidace napříč procesy by potřebovala to, co otisk dává zdarma v rámci jednoho; kontraktem zůstává znovuobjevení po restartu.
• Pevně zadaný očekávaný počet cílů měření výkonu v testu: jmenovatel je ten z registru; počet napsaný člověkem je drift, který mise zakazuje.
• Jeden soubor inventáře měření výkonu vedle kódu: byl by druhým registrem, který celý návrh odmítá; projekce se počítá z deskriptorů.
• Pevně zadané prahy reálného času v CI: šum prostředí by je činil buď planými, nebo nestabilními; politika jsou data, základní linie je na platformu a strukturální počítadla jsou tvrdou kontrolou.

Důsledky

Přidání schopnosti do existujícího modulu je jeden blok capability!, jeho typovaný vstup a výstup a BenchmarkCases vstupu; majordomus generate obnoví potvrzené projekce a capabilities validate dokáže zbytek. Přidání modulu je jeden modul v Rustu s module() a jedno jméno v compose_modules!. Otisk registru, čítače, výsledek měření výkonu a schémata pokrytí, klíče cílů a vygenerovaná sada souborů se stávají povrchy kompatibility. capabilities.list už schémata nenese; klient, který nějaké potřebuje, volá capabilities.describe. Sdílený server si ponechává index, který sestavil při startu; čítače to činí viditelným místo skrytého.

Strategie testování

Nejdřív black-box: tests/hot_path.rs (čítače napříč stovkami skutečných požadavků), tests/bench.rs (odvození, vystavení a propagace politiky, tři runnery, kontrola, příkazová řádka), tests/executor.rs (sémantika cache přes exekutor), tests/properties.rs (založené na vlastnostech, řízené registrem), tests/projections.rs (každá projekce a každý generovaný artefakt), tests/registry.rs (invarianty modulů), test/cases/91_canonical_architecture.sh (totéž přes sestavenou binárku v repozitáři, který zapsal init). Měření výkonu: benches/projections.rs, benches/shared.rs, benches/scaling.rs nad syntetickým repozitářem a samotný majordomus bench. Kontroly z ADR 2 získávají bench coverage --check v scripts/rust-check a v CI.