Reprodutseeritavus ja päritolu
Kshana on ehitatud reprodutseeritavaks: samad sisendid annavad samad tulemused ja ehituse artefakte saab jälgida tagasi neid tootnud lähtekoodini. See dokument ütleb täpselt, mis on tagatud, mis mitte ja kuidas tagatisi jõustatakse.
Determinismi tagatised#
Mootoril ei ole seinakella, täitmislõimest sõltuvust ega algväärtustamata juhuslikkust. Iga juhuslik protsess on juhitud voo ChaCha8Rng poolt, mis on võtmestatud stsenaariumi seed järgi ja tõmmatud fikseeritud järjekorras. Tagajärjed:
| Omadus | Tagatud | Jõustab |
|---|---|---|
Sama stsenaarium, sama masin → bait-baidilt identne result.json |
Jah | scripts/check-reproducible.sh (käitab etalonstsenaariumi kaks korda, võrdleb SHA-256 (SHA: Secure Hash Algorithm)) |
| Sama stsenaarium → identsed headusarvud väli väljalt | Jah, platvormi kaupa | tests/golden.rs fikseerib iga headusarvu (FoM) nelja etalonstsenaariumi jaoks |
Stsenaariumi sisendräsi (scenario_hash) on platvormist sõltumatu |
Jah | kanoonilise stsenaariumi sisupõhine SHA-256, fikseeritud failis tests/golden.rs |
| Sisendi sõrmejälg + väljundi kuju identsed üle OS-i (operatsioonisüsteemi) | Jah | tests/cross_platform_golden.rs fikseerib täpse SHA-256 stsenaariumi kohta (kümme stsenaariumi, üks .sha256 fail igaühe kohta kaustas tests/golden/), kontrollituna 3-OS CI (pidev integratsioon) maatriksil |
| Väljundi väärtused langevad kokku üle OS-i (ubuntu/macOS/Windows) | Jah, täpsusega 1e-6 | CI töö reproducibility-matrix käitab golden.rs (1e-6), sgp4_verification.rs (2e-5 km) ja determinism.rs kõigil kolmel OS-il |
| Madala Maa orbiidi (LEO) navigatsioonisõnumi kaader on samad baidid igal platvormil ja igas ehitusprofiilis, WebAssembly (WASM) ehitus kaasa arvatud | Jah | src/portable_math.rs (iga transtsendentne funktsioon ja iga normaaljaotuse tõmme liigis leo-navmsg läheb läbi puhta Rusti kasti libm); leo_navmsg::tests::the_encoded_frame_is_the_same_bytes_on_every_platform fikseerib terve kaadri ilma platvormi väravata |
| Algväärtustatud indeksitõmbed (bootstrap-valim, segamised) on samad 32-bitistel ja 64-bitistel sihtidel | Jah | portable_math::uniform_index valib alati kujul u64; fikseeritud failis portable_math::tests |
| Igal pool sama tööriistaahel | Jah | rust-toolchain.toml fikseerib kanali; scripts/check-toolchain.sh laseb ehituse triivi korral ebaõnnestuda; CI ja väljalase fikseerivad sama versiooni |
| Sama sõltuvuste komplekt | Jah | Cargo.lock on sissekantud ja cargo metadata --locked kasutatakse SBOM-i jaoks (tarkvara komponentide loetelu) |
Iga käsurea käivitus kirjutab oma aruandesse ka reprodutseeritavuse kirje (<scenario>.report.json ja .report.html): mootori versioon, stsenaariumifaili ja tulemusdokumendi SHA-256, algväärtus, platvorm ja täpne käsk, mida tests/advanced_report_cli.rs uuesti käitab bait-baidilt identse tulemuseni. Aruanne on ise jooksu puhas funktsioon: kaks käivitust scenarios/clock-holdover.toml kirjutavad sama report.json bait-baidilt. Vt REPORTS.md.
Platvormideülene hoiatus (ja kuidas etalonväärtused sellega toimivad)#
Arvulised tulemused on antud platvormil bitisammuti identsed, kuid võivad platvormide vahel erineda viimaste ühikute viimases kohas (ULP). Põhjus on platvormi matemaatikateek: sqrt, ln, exp ja sarnased ei pea IEEE-754 (IEEE: Institute of Electrical and Electronics Engineers) järgi olema korrektselt ümardatud, seega võivad Linux (glibc, GNU C teek), macOS ja Windows igaüks tagastada erineva viimase biti. Pikal jooksul kogunevad need ~1e-16 erinevused ehk ~1e-12 suhtelisele.
Kaks asja teevad selle viimase koha erinevuse suuremaks kui see algab ja mõlemad on mõõdetud, mitte eeldatud. Adaptiivne integraator valib oma järgmise sammu veahinnangust viienda juure kaudu, nii et üks ühik viimases kohas muudab sammujada ja kaks platvormi nõustuvad siis ainult integreerimistolerantsi täpsuseni. Iteratiivne hindaja (vähimruutude sobitus, orbiidi määramise filter) võib minna kokkuläbimiseni teist rada. Mõlemale ehitatud liigid võivad platvormide vahel üksikutel väljadel erineda rohkem kui 1e-6; src/test_support.rs salvestab sama režiimi ühikutestide jaoks.
Ehitusprofiil loeb samamoodi, ühel masinal. Optimeeritud ehitus macOS-il liidab ühe argumendi siinuse ja koosinuse üheks väljakutseks süsteemi ühisrutiinile, mille siinus erineb üksiku sin viimases bitis 379 argumendi puhul 200 000-st; optimeerimata ehitus teeb need kaks väljakutset. Mõõdetud aarch64 macOS-il 138 stsenaariumifaili peal annavad ühe lähtekoodi silumis- ja väljalaskeehitus bait-baidilt identsed tulemusdokumendid 102 jaoks. Ülejäänud 36 erinevad viimastes kohtades: 28 täpsusega 1e-6, üks (leo-ppp-convergence) 2.8e-6 võrra ja seitse kampaaniat ainult oma liikmete jooksude räsides; ükski ei erine sildis, arvus ega verdiktis. Ülaltoodud bait-baidilt identsuse tagatis kehtib seega ühe ehituse kohta: sama kahendfail kaks korda.
Algväärtustatud normaaljaotuse tõmmetel on kolmas, palju harvem allikas: valimi võtja kutsub oma harvades harudes hosti eksponent- ja logaritmfunktsiooni ning umbes üks tõmme miljonist erineb natiivse ja WASM-ehituse vahel viimase biti poolest.
Kui väljund on diskreetne, ei ole viimase koha erinevus üldse vastuvõetav ja liik arvutatakse hosti teegi asemel funktsiooniga src/portable_math.rs. Liik leo-navmsg on esimene: selle kahendkaader on edastatud täisarvud ja sama stsenaarium kodeeriti kord kolmeks erinevaks kaadriks: väljalaskeehituses, sama lähtekoodi silumisehituses ja brauseris. Nüüd on see kõigis kolmes samad baidid.
Seetõttu etalontestid ei fikseeri ujukomaväljundi ühte platvormideülest räsi — see oleks habras ja laseks teisel OS-il ebaõnnestuda ka õigesti ehitatud ehitustel. Selle asemel:
tests/golden.rsfikseerib iga headusarvu suhtelise tolerantsiga1e-6— neli suurusjärku täpsem kui mis tahes reaalne regressioon (mis liigutab väärtust terve protsendi võrra), kuid palju lõdvem kui platvormideülene matemaatikateegi (libm) värin. Ruudustikuga piiratud väljad (holdover-sekundid) ja täpselt nulliga väljad fikseeritakse täpselt.scenario_hash— sisendite sisuräsi — on platvormist sõltumatu ja fikseeritud täpselt.tests/cross_platform_golden.rsfikseerib täpse SHA-256, sissekantud stsenaariumi kohta failistests/golden/, projektsiooni kohta, mis on platvormide vahel identne: sisendi sõrmejälg pluss väljundi kuju (väljade nimed, pesastus, lehetüübid, massiivide pikkused — fikseeritud deterministliku ruudustikuaritmeetikaga, mitte kunagi ujukomaväärtustega). See tabab struktuurilisi regressioone täpselt, samal ajal kui ülaltoodud tolerantsifikseeringud tabavad väärtuste regressioone.scripts/check-reproducible.shjõustab bait-baidilt identse väljundi kahe jooksu vahel samal masinal (determinismi tagatis).- CI töö
reproducibility-matrixkäitab neli ülaltoodud testi (cross_platform_golden,golden,determinism,sgp4_verification) platvormidel ubuntu-latest, macos-latest ja windows-latest, nii et platvormideülest reprodutseeritavust väidetakse igal push'il — kuju/sisendi etalonid täpselt, arvväärtused täpsusega 1e-6 ja SGP4 (Simplified General Perturbations 4) olekud täpsusega 2e-5 km — mitte ei toetuta ühele OS-ile.
Kui peate fikseeritud arvud uuesti genereerima (nt pärast ettenähtud mudelimuutust), käitage iga etalonstsenaarium ja kopeerige prinditud FoM-väärtused faili tests/golden.rs, seejärel märkige muutus faili CHANGELOG.md.
Tarkvara komponentide loetelu (SBOM)#
scripts/gen-sbom.sh väljastab CycloneDX 1,5 SBOM-i, mis loetleb iga kasti, mis kuulub kshana artefakti, koos selle täpse versiooni, allika ja litsentsiga. See on sõltuvusteta generaator, mis on ehitatud peale cargo metadata --locked (nii et see töötab ainult tööriistaahelaga) ja see käib läbi lahenduse graafi kshana paketist läbi tavaliste ja ehitussõltuvuste. Arendussõltuvused (ainult testiks mõeldud kastid, nagu sgp4) on välja jäetud, sest ükski artefakt neid ei sisalda.
Graaf on nende funktsioonikomplektide ühend, millega tarnitavad artefaktid on ehitatud: vaikeehitus (teek ja käsurealiides (CLI)), --features python (PyPI (Python Package Index) wheel, mille pyo3 ahel on selle võõrfunktsiooniliides) ja --features wasm (npm pakett, mis kannab seda sama SBOM-i oma tarballis). Platvormitingimuslikud sõltuvused igale sihile on kaasatud, sest wheel'id tarnitakse mitmele operatsioonisüsteemile ja npm pakett sihib WebAssembly't. Üks dokument katab kõik kolm artefakti, seega on see iga üksiku jaoks ülemhulk. Praegu loetleb see 107 komponenti; arv on fikseeritud failis tests/fixtures/reproducibility_software_assurance/. Eraldiseisval serveril kshana-mcp on oma manifest ja seda see SBOM ei kirjelda.
Väljund on deterministlik — sama sõltuvuste komplekt annab bait-baidilt identse dokumendi, sealhulgas järjenumbri, mis on tuletatud sorteeritud pakettide loendist, mitte ajatemplist.
Väljalaske töövoog genereerib SBOM-i (kshana-sbom.cdx.json) ja lisab selle igale märgendatud väljalaskele; avaldamise töövoog tarnib selle ka PyPI wheel'ide kõrval ja npm paketi sees.
Ehituse päritolu#
Väljalaske töövoog toodab SLSA (Supply-chain Levels for Software Artifacts) ehituse päritolu tõendi (actions/attest-build-provenance), mis katab iga faili, mille see GitHubi väljalaskele lisab: iga platvormi käsurea kahendfailid, serveri kshana-mcp kahendfail, SBOM, valideerimiskokkuvõte ja SHA256SUMS. Tarbija saab käsuga gh attestation verify kontrollida, et artefaktid ehitas selle hoidla väljalaske töövoog sellest lähtekoodist — sulgedes lõhe „siin on kahendfail“ ja „siin on kahendfail, mille ma saan lähtekoodini jälgida“ vahel. Näiteks versiooni v0.28.0 SBOM-i jaoks:
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