Úloha, která deklaruje závazky, dosáhne výsledku completed, jen když má každý z nich proti sobě zaznamenané důkazy, a důkazy pořízené nad soubory, které se od té doby změnily, nebo na commitu, který branch od té doby opustila, už nic nesplňují

Co to znamená

Úloha může vedle scope deklarovat requires. Rozsah je slib vymezení — kam smí worker zapisovat. requires je slib dodání — co worker dluží, než je dostupný výsledek completed. Tokeny jsou deklarovány v share/obligations.yaml: implementation, tests, docs, generated, rules, commit, push, target, pages, deploy, verify.

majordomus evidence --covers <token> zaznamená, že jedna z nich byla splněna, s uvedením příkazu nebo artefaktu, který to vytvořil — vyprávění není důkaz — a hashe sledovaných souborů, které závazek jmenuje. Čtyři tokeny se nikdy nezaznamenávají: commit, push, target a pages pojmenovávají fakta, která nástroj zjišťuje sám, a obligation-establishment je ta polovina příběhu. check a finish vyhodnocují každý deklarovaný závazek při každém běhu přes doktrínu majordomus.obligation-closure. Závazek bez důkazu selže. Závazek, jehož zaznamenaný vstupní hash už neodpovídá stromu, selže s uvedením obou hashů. Závazek, jehož fakt je vzdálený — push, integrace, publikace, nasazení — je místo toho vázán na commit, ve kterém byl vzat, a selže, jakmile větev tento commit opustí.

Odmítnut je jen výsledek completed. Úloha, která hlásí partial nebo blocked, je poctivá, a odmítnutí by ji naučilo místo toho tvrdit completed.

Princip

mj_validate_obligations v lib/evidence.sh čte requires úlohy, pak pro každý token čte z knihy nejnovější řádek task.evidence pro danou úlohu. Důkaz je řádek knihy, ne nové úložiště, protože kniha je už pouze pro přidávání, uspořádaná a kontrolovaná na integritu a její obálka už nese head, branch a relaci.

Aktuálnost se rozhoduje přepočtem, nikdy časovým razítkem. mj_obligation_inputs_hash rozbalí pathspec povinnosti pomocí git ls-files a zahashuje je přes mj_inputs_hash v lib/common.sh — toutéž implementací, přesunutou tam z generátoru webu, která vytváří vlastní source_hash webu. Takže „jsou tyto důkazy stále pravdivé?“ a „je publikovaný web stále aktuální?“ je tatáž otázka kladená různým vstupům. U vzdálené povinnosti nejsou žádné vstupy a rozhoduje mj_git_label čtyřmi hodnotami, které už zbytek repozitáře používá: exact, advanced, diverged, different_context. Žádný pátý slovník nebyl vymyšlen.

Jeden reportér, mj_obl_verdict, rozhoduje, zda nedostatek odmítne, nebo jen ohlásí, takže úsudek je napsán jednou a check může jmenovat zastaralé důkazy, aniž by blokoval práci.

Jak to vidět

majordomus start "a change" --scope lib/
# declare what it owes, then try to finish without proving it
majordomus finish --outcome completed --note "done"
# FAIL obligation  tests — owed, and no evidence was recorded; exit 10

majordomus evidence --covers tests --type test --command 'bash test/run.sh'
# evidence: tests recorded for t-... (inputs 28a9ccc503fb)
majordomus check     # OK obligation tests — discharged over inputs 28a9ccc503fb

echo change >> lib/a && git add -A && git commit -qm change
majordomus finish --outcome completed --note "done"
# FAIL obligation  tests — the evidence was taken over inputs 28a9ccc503fb and this tree
#                  hashes to 8c27a0fd8ec7; it no longer describes what it proved

Co nepokrývá

Neposuzuje, zda příkaz, který pracovník uvede, skutečně dokazuje závazek: úloha může zaznamenat --command true proti tests a kniha to udrží. Odstraňuje možnost, aby tento záznam přežil změnu, kterou měl popisovat. Sám nic nespouští a nevymýšlí závazky — úloha, která žádné nedeklaruje, se chová přesně jako dřív, což je to, co dnes dělá každá úloha v tomto repozitáři.

Ze vzdálených tokenů deploy a verify stále závisejí na faktech, které notebook sám nezjistí; jejich důkaz jmenuje commit a čas a poctivým hlášením pro práci, která trunk nedosáhla, je, že povinnost není splněna.

Proč existuje

Kontrakt finish už odmítal, ale vše, kvůli čemu odmítal, bylo uvnitř pracovního stromu. Worker mohl splnit každý řádek, zatímco práce byla necommitnutá, nepushnutá, chyběla v trunku, nebyla publikována ani ověřena, a záznam by řekl completed. Implementováno, commitnuto, pushnuto, začleněno a nasazeno je pět různých faktů.

Druhá polovina je horší a tišší. Důkaz, který nemůže vypršet, je tvrzení o minulosti vydávané za tvrzení o přítomnosti. Výsledek testu zaznamenaný před změnou neříká nic o stromu, který existuje po ní, a zpráva, která obojí pokládá za totéž, je způsob, jak „done“ začne znamenat nic konkrétního.