Reprodukovatelnost a původ
Kshana je budována tak, aby byla reprodukovatelná: stejné vstupy dávají stejné výsledky a artefakty sestavení lze vysledovat ke zdroji, z něhož vznikly. Tento dokument přesně uvádí, co je zaručeno, co ne a jak se záruky vynucují.
Záruky determinismu#
Engine nemá žádné nástěnné hodiny, žádnou závislost na vláknu provádění a žádnou nenasazovanou (unseeded) náhodnost. Každý stochastický proces je řízen proudem ChaCha8Rng zadaným seed scénáře a čerpaným v pevném pořadí. Důsledky:
| Vlastnost | Zaručeno | Vynucuje |
|---|---|---|
Stejný scénář, stejný počítač → bajt po bajtu shodný result.json |
Ano | scripts/check-reproducible.sh (spustí referenční scénář dvakrát, porovná SHA-256 (SHA: Secure Hash Algorithm)) |
| Stejný scénář → shodné ukazatele kvality pole po poli | Ano, pro každou platformu | tests/golden.rs fixuje každý ukazatel kvality (FoM) pro čtyři referenční scénáře |
Otisk vstupu scénáře (scenario_hash) je nezávislý na platformě |
Ano | SHA-256 kanonického scénáře adresovaný obsahem, fixovaný v tests/golden.rs |
| Otisk vstupu + tvar výstupu shodné napříč OS (operační systém) | Ano | tests/cross_platform_golden.rs fixuje přesný SHA-256 pro každý scénář (deset scénářů, po jednom souboru .sha256 v tests/golden/), kontrolovaný na matici CI (průběžná integrace) se 3 OS |
| Hodnoty výstupu souhlasí napříč OS (ubuntu/macOS/Windows) | Ano, na 1e-6 | úloha CI reproducibility-matrix spouští golden.rs (1e-6), sgp4_verification.rs (2e-5 km) a determinism.rs na všech třech OS |
| Rámec navigační zprávy na nízké oběžné dráze Země (LEO) má stejné bajty na každé platformě a v každém profilu sestavení, včetně sestavení WebAssembly (WASM) | Ano | src/portable_math.rs (každá transcendentní funkce a každá normální odchylka druhu leo-navmsg prochází čistě rustovým crate libm); leo_navmsg::tests::the_encoded_frame_is_the_same_bytes_on_every_platform fixuje celý rámec bez omezení platformy |
| Seedované losování indexů (bootstrap resampling, míchání) je stejné na 32bitových i 64bitových cílech | Ano | portable_math::uniform_index vždy vzorkuje jako u64; fixováno v portable_math::tests |
| Všude stejný toolchain | Ano | rust-toolchain.toml fixuje kanál; scripts/check-toolchain.sh při odchylce shodí sestavení; CI i vydání fixují stejnou verzi |
| Stejná sada závislostí | Ano | Cargo.lock je zapsán do repozitáře a cargo metadata --locked se používá pro SBOM (soupis softwarových komponent) |
Každý běh z příkazové řádky také zapíše do své zprávy záznam reprodukovatelnosti (<scenario>.report.json a .report.html): verzi enginu, SHA-256 souboru scénáře a dokumentu výsledku, seed, platformu a přesný příkaz, který tests/advanced_report_cli.rs znovu spustí na bajt po bajtu shodný výsledek. Zpráva je sama čistou funkcí běhu: dva běhy scenarios/clock-holdover.toml zapíší stejný report.json bajt po bajtu. Viz REPORTS.md.
Výhrada ke shodě napříč platformami (a jak s ní zacházejí golden testy)#
Numerické výsledky jsou bitově shodné na dané platformě, ale mohou se mezi platformami lišit v posledních několika jednotkách na posledním místě (ULP). Příčinou je matematická knihovna platformy: sqrt, ln, exp a podobné funkce nemusejí podle IEEE-754 (IEEE: Institute of Electrical and Electronics Engineers) být správně zaokrouhlené, takže Linux (glibc, knihovna GNU C), macOS a Windows mohou každý vrátit jiný poslední bit. V dlouhém běhu se tyto rozdíly řádu ~1e-16 hromadí na možná ~1e-12 relativně.
Dvě věci zvětšují rozdíl na posledním místě oproti jeho počátku a obě jsou změřeny, nikoli předpokládány. Adaptivní integrátor volí svůj příští krok z odhadu chyby pomocí páté odmocniny, takže jedna jednotka na posledním místě změní posloupnost kroků a obě platformy se pak shodnou jen na toleranci integrace. Iterativní estimátor (proložení metodou nejmenších čtverců, filtr určování oběžné dráhy) může ke konvergenci dojít jinou cestou. Druhy postavené na kterémkoli z nich se mohou mezi platformami lišit o více než 1e-6 v jednotlivých polích; src/test_support.rs zaznamenává stejný režim pro jednotkové testy.
Profil sestavení záleží stejným způsobem, na jednom stroji. Optimalizované sestavení na macOS sloučí sinus a kosinus jednoho argumentu do jednoho volání systémové kombinované rutiny, jejíž sinus se od samostatného sin liší v posledním bitu u 379 z 200 000 argumentů; neoptimalizované sestavení provede dvě volání. Změřeno na aarch64 macOS nad 138 soubory scénářů: debug a release sestavení jednoho zdroje dávají bajt po bajtu shodné dokumenty výsledků u 102. Zbylých 36 se liší v posledních místech: 28 do 1e-6, jeden (leo-ppp-convergence) o 2.8e-6 a sedm kampaní jen v otiscích běhů svých členů; žádný se neliší v popisku, počtu ani verdiktu. Výše uvedená záruka bajtové shody platí proto pro jedno sestavení: tentýž binární soubor dvakrát.
Seedovaná normální losování jsou třetím, mnohem vzácnějším zdrojem: vzorkovač ve svých vzácných větvích volá hostitelskou exponenciálu a logaritmus a asi jedno losování z milionu se v posledním bitu mezi nativním a WASM sestavením liší.
Kde je výstup diskrétní, rozdíl na posledním místě není přijatelný vůbec a druh se počítá pomocí src/portable_math.rs místo hostitelské knihovny. Prvním je druh leo-navmsg: jeho binární rámec jsou přenášená celá čísla a tentýž scénář byl jednou zakódován do tří různých rámců: v release sestavení, v debug sestavení téhož zdroje a v prohlížeči. Nyní jsou ve všech třech stejné bajty.
Z tohoto důvodu golden testy nefixují jediný otisk výstupu s plovoucí řádovou čárkou platný napříč platformami — ten by byl křehký a poctivě správná sestavení na jiném OS by neprošla. Místo toho:
tests/golden.rsfixuje každý ukazatel kvality s relativní tolerancí1e-6— o čtyři řády přísnější než jakákoli skutečná regrese (která posune hodnotu o celá procenta), přesto mnohem volnější než kolísání matematické knihovny (libm) napříč platformami. Pole omezená mřížkou (sekundy holdoveru) a pole přesně nulová se fixují přesně.scenario_hash— otisk obsahu vstupů — je nezávislý na platformě a fixuje se přesně.tests/cross_platform_golden.rsfixuje přesný SHA-256, zapsaný pro každý scénář vtests/golden/, nad projekcí, která napříč platformami shodná je: otisk vstupu plus tvar výstupu (názvy polí, vnoření, typy listů, délky polí — dané deterministickou mřížkovou aritmetikou, nikdy hodnoty s plovoucí řádovou čárkou). Tím se přesně zachytí strukturální regrese, zatímco výše uvedené tolerance zachytí regrese hodnot.scripts/check-reproducible.shvynucuje bajt po bajtu shodný výstup ve dvou během na témže počítači (záruka determinismu).- Úloha CI
reproducibility-matrixspouští čtyři výše uvedené testy (cross_platform_golden,golden,determinism,sgp4_verification) na ubuntu-latest, macos-latest a windows-latest, takže se reprodukovatelnost napříč platformami potvrzuje při každém pushi — golden testy tvaru a vstupu přesně, numerika na 1e-6 a stavy SGP4 (Simplified General Perturbations 4) na 2e-5 km — místo spoléhání na jediný OS.
Pokud potřebujete zafixovaná čísla přegenerovat (například po záměrné změně modelu), spusťte každý referenční scénář a vypsané hodnoty FoM zkopírujte do tests/golden.rs, pak změnu poznamenejte v CHANGELOG.md.
Soupis softwarových komponent (SBOM)#
scripts/gen-sbom.sh vydává SBOM CycloneDX 1,5 uvádějící každý crate, který je součástí artefaktu kshana, s jeho přesnou verzí, zdrojem a licencí. Je to generátor bez závislostí postavený na cargo metadata --locked (takže funguje jen s toolchainem) a prochází graf rozlišení od balíčku kshana jen přes běžné závislosti a závislosti sestavení. Vývojové závislosti (crate jen pro testy, například sgp4) jsou vyloučeny, protože je žádný artefakt neobsahuje.
Graf je sjednocením sad funkcí, s nimiž se dodávané artefakty sestavují: výchozí sestavení (knihovna a CLI (rozhraní příkazové řádky)), --features python (kolečko PyPI (Python Package Index), jehož řetěz pyo3 je jeho hranicí cizích funkcí) a --features wasm (balíček npm, který nese tentýž SBOM ve svém tarballu). Zahrnuty jsou závislosti podmíněné platformou pro každý cíl, protože kolečka se dodávají pro několik operačních systémů a balíček npm cílí na WebAssembly. Jeden dokument pokrývá všechny tři artefakty, takže pro kterýkoli z nich je nadmnožinou. V současnosti uvádí 107 komponent; počet je fixován v tests/fixtures/reproducibility_software_assurance/. Samostatný server kshana-mcp má vlastní manifest a tento SBOM jej nepopisuje.
Výstup je deterministický — stejná sada závislostí dává bajt po bajtu shodný dokument, včetně sériového čísla odvozeného ze seřazeného seznamu balíčků místo časového razítka.
Pracovní postup vydání generuje SBOM (kshana-sbom.cdx.json) a přikládá jej ke každému označenému vydání; pracovní postup publikace jej dodává také vedle koleček PyPI a uvnitř balíčku npm.
Původ sestavení#
Pracovní postup vydání vytváří atestaci původu sestavení SLSA (Supply-chain Levels for Software Artifacts) (actions/attest-build-provenance), která pokrývá každý soubor, který přikládá k vydání na GitHubu: binární soubory příkazové řádky pro každou platformu, binární soubor serveru kshana-mcp, SBOM, souhrn validace a SHA256SUMS. Konzument může pomocí gh attestation verify ověřit, že artefakty byly sestaveny pracovním postupem vydání tohoto repozitáře z tohoto zdroje — a tím zaplnit mezeru mezi „tady je binární soubor“ a „tady je binární soubor, který mohu vysledovat ke zdroji“. Například pro SBOM verze v0.28.0:
curl -sLO https://github.com/AshfordeOU/kshana/releases/download/v0.28.0/kshana-sbom.cdx.json
gh attestation verify kshana-sbom.cdx.json --repo AshfordeOU/kshana