Preflight

Vstup do repozitáře Majordomus odpoví na jednu otázku za dobu, kterou zabere cd: platí zde Majordomus skutečně, v jakém kontextu pracuji, které integrace žijí a která tvrzení jsou právě teď prokázána? Odpovědí je jedna typovaná hodnota, environment::preflight::Preflight, sestavená v apps/majordomus-cli/src/environment/preflight.rs. Každý povrch tuto hodnotu vykresluje a žádný nepočítá vlastní stav. Chování tak, jak je implementováno a testováno; kde se tento dokument a spustitelný kód rozcházejí, má chybu dokument.

Pravidlem je project.entry-reports-only-evidence (.ai/repo/rules/project/entry-reports-only-evidence.v1.md); rozhodnutím je ADR 0066.

Architektura

flowchart TD
  state["repository state<br/><small>git, .ai/local/state, lease, evidence ledger, gh-pages ref, index</small>"]
  observations["Observations<br/><small>plain data</small>"]
  preflight["Preflight<br/>environment.preflight<br/><small>sections of checks, each a verdict and its evidence</small>"]
  state -->|"observe(): the only reading; bounded, loopback only, never a build"| observations
  observations -->|"derive(): pure; every verdict is a test over a value"| preflight
  preflight --> enter["env enter<br/><small>the compact line drawn on entering (direnv, via .envrc)</small>"]
  preflight --> full["majordomus env preflight<br/><small>full, --compact, --format json, --full</small>"]
  preflight --> http["GET /api/v1/environment/preflight"]
  preflight --> mcp["MCP<br/><small>tool majordomus_preflight, resource majordomus://environment/preflight</small>"]
  preflight --> cockpit["Cockpit overview<br/><small>the Preflight card, each verdict as data-check / data-verdict</small>"]

RepositoryEnvironment (ENVIRONMENT.md) říká, čím checkout je. Preflight říká, co je o něm dokázáno. Obě jsou záměrně samostatné hodnoty. Sloučení důkazu do snapshotu by měnilo jeho digest, takže každý banner by se četl jako novinka.

Bootstrap repozitáře

.envrc je nezměněno: provede jedno volání, bin/majordomus-env enter --shell direnv, a vyhodnotí, co toto volání exportuje (project.envrc-is-an-adapter). Volání rozliší snapshot, zajistí runtime a pak vykreslí banner následovaný kompaktním preflightem, vše ze stejných odečtů. Samostatný řádek majordomus env preflight --compact v .envrc by byl druhým git status při každém cd, což pravidlo adaptéru zakazuje. Bootstrap soubory klienta (.mcp.json, .gemini/settings.json, .codex/config.toml) spouštějí launcher a o ničem nerozhodují.

Sémantika stavů

První tři nelze vytvořit bez důkazů. Check::new mění holé tvrzení o platnosti na unknown, takže žádný renderer nemůže nakreslit úspěch, který nic nepodpírá. attention vypíše každou kontrolu, která potřebuje pohled, nejnaléhavější první: failed, degraded, stale, unavailable, unknown.

Kontroly

Stav řízení

Soubor pravidla na disku je objeven. governance.rules je active, když rules.report spočítal korpus na HEAD, což znamená, že je načten. Jeho souhrn uvádí, kolik pravidel blokuje, kolik jich je vlastních projektu a kolik převzatých a kolik jich spouští kontrola CI. Vynuceno a ověřeno patří verification.enforcement. Tato kontrola je verified jen tehdy, když je každé pravidlo, které dluží spustitelný důkaz, proven proti stromu. Existující kontrola není verdikt, který prošel, takže korpus, který je kontrolovaný a nikdy nespuštěný, je degraded. ADR se počítají jako indexované; nic nespojuje ADR s úlohou, takže žádné se netvrdí za relevantní.

Čerstvost kontextu relace

Briefing epizody je přesný na commitu a stromu, na kterých byl napsán. Je stale, jakmile se pohne HEAD, pod ním se změní strom nebo po něm začne úloha. Shrnutí pojmenuje, co z toho nastalo, a majordomus context zapíše aktuální briefing. Briefing napsaný nad dirty stromem je unknown spíše než fresh: epizoda zaznamenává slovo dirty, ne které změny, takže úpravu nebo revert od té doby nelze vidět. Preflight nikdy sám kontext neregeneruje: entry není místem pro zápis, který vlastní vlastní životní cyklus providera. V checkoutu zatím neexistuje žádná zkompilovaná revize kontextu, takže se žádná nezobrazuje.

detekce MCP a Cockpitu

Lease na disku je nárok, ne server. Server je verified jen tehdy, když adresa, kterou lease jmenuje, odpovídá GET / jako držitel lease tohoto checkoutu, ve verzi tohoto spustitelného souboru. To je lease::probe_reply, totéž rozhodnutí, jaké dělá volba launcheru, s rozpočtem 250 ms. Server, který odpovídá z jiného kódu, je degraded. Lease, jehož adresa neodpovídá, je failed. Žádné lease je unavailable. Kontroly MCP, API a Cockpitu čtou příznak ready, který index samotného serveru uvádí pro každý povrch. Banner už neoznačuje službu jako odpovídající, pokud server není ověřen. MAJORDOMUS_URL se stále exportuje, protože klient může adresu stále zastihnout. Obsloužený požadavek držící lease je vlastním důkazem a čte vlastní nástěnku peerů.

Ověřovací důkazy

Běh v evidenčním registru ověřuje strom jen podle definice „prokázáno“ z modulu důkazů: prošel, jeho test má stále zaznamenaný hash a strom před vámi je tím stromem, který běh měřil, bez vlastního řádku registru. Běh na jakémkoli jiném stromě je stale. Toto porovnání stojí git dva procesy na každý zaznamenaný commit, proto se jeho odpovědi ukládají do cache v .ai/local/state/environment/snapshot.json. Cache je klíčovaná podle HEAD, každé cesty, kterou git hlásí jako změněnou, a souboru registru, takže jakákoli změna ji přepočítá. Obsloužený požadavek cache nikdy nezapisuje. Pokrytí se hlásí jako unavailable, dokud měření pokrytí nezanechá v repozitáři záznam.

Čerstvost nasazení

scripts/pages publikuje do gh-pages a každý commit nasazení jmenuje zdrojový commit, z něhož byl sestaven. Preflight čte lokální ref refs/remotes/origin/gh-pages. Nasazení je verified, když je tímto zdrojem HEAD, stale, když je jiným commitem, a unavailable bez refu. Ref je jen tak čerstvý jako poslední fetch a důkaz to říká. Zda GitHub tento commit servíruje, je věcí scripts/pages verify. Lokální stav runtime se na statický web nikdy nepublikuje.

Záruky výkonu

Vstup nikdy nesestavuje index. Součet pravidel pochází z cache, kterou zapisuje env preflight --full, označené commitem, u něhož byl spočten. Vstup se nikdy neptá nástěnky peerů, což stojí oběh, který sesbírá nástěnku každého checkoutu. Nikdy nespouští test, build, generátor ani vzdálený požadavek. Jeho jediný socket míří na loopback adresu, kterou jmenuje lease.

Měření níže bylo pořízeno 2026-09-15, debug build, v linked worktree tohoto repozitáře, zatímco na stejném stroji sestavovalo několik dalších relací. Je to teplý vstup přes bin/majordomus-env enter --shell direnv, volání, které provádí .envrc:

Preflight tedy přidá k teplému vstupu asi 30–70 ms. Podlahou pod ním je vstup, který tam už byl. Každý proces gitu na tomto stroji stál při té zátěži 40–90 ms a porovnání knihy jsou dva z nich na zaznamenaný commit, proto se jeho odpovědi cachují. Cíle mandátu 50 ms teplý, 150 ms studený a 250 ms tvrdý na tomto stroji nejsou splněny. Rozpočty, které repozitář vynucuje, jsou benchmark.budget.enter_ms (750 ms) a enter_cold_ms (1000 ms) politiky, měřené test/cases/190 při každém běhu.

Řešení problémů