Toistettavuus ja alkuperä

Kshana on rakennettu toistettavaksi: samat syötteet tuottavat samat tulokset, ja käännösartefaktit voidaan jäljittää lähteeseen, josta ne syntyivät. Tämä asiakirja kertoo täsmälleen, mitä taataan, mitä ei, ja miten takuut pannaan täytäntöön.

Determinismitakuut#

Moottorissa ei ole kellonaikariippuvuutta, ei suoritussäikeestä riippuvuutta eikä siementämätöntä satunnaisuutta. Jokaista stokastista prosessia ohjaa virta ChaCha8Rng, jonka avaimena on skenaarion kenttä seed ja josta arvot vedetään kiinteässä järjestyksessä. Seurauksia:

Ominaisuus	Taattu	Varmistaa
Sama skenaario, sama kone → tavu tavulta sama tiedosto `result.json`	Kyllä	`scripts/check-reproducible.sh` (ajaa vertailuskenaarion kahdesti, vertaa SHA-256-tiivisteitä (SHA: Secure Hash Algorithm))
Sama skenaario → samat laatumittarit kenttä kentältä	Kyllä, alustakohtaisesti	`tests/golden.rs` lukitsee jokaisen laatumittarin (FoM) neljälle vertailuskenaariolle
Skenaarion syötetiiviste (`scenario_hash`) ei riipu alustasta	Kyllä	kanonisen skenaarion sisältöosoitteinen SHA-256, lukittu tiedostossa `tests/golden.rs`
Syötteen sormenjälki + tulosteen muoto identtinen eri käyttöjärjestelmissä (OS)	Kyllä	`tests/cross_platform_golden.rs` lukitsee tarkan SHA-256-tiivisteen skenaariota kohti (kymmenen skenaariota, yksi tiedosto `.sha256` kutakin kohti hakemistossa `tests/golden/`), ja se tarkistetaan 3 käyttöjärjestelmän CI-matriisissa (jatkuva integrointi)
Tulosteen arvot täsmäävät käyttöjärjestelmien kesken (ubuntu/macOS/Windows)	Kyllä, tarkkuudella 1e-6	CI-työ `reproducibility-matrix` ajaa testit `golden.rs` (1e-6), `sgp4_verification.rs` (2e-5 km) ja `determinism.rs` kaikilla kolmella käyttöjärjestelmällä
Matalan Maan kiertoradan (LEO) navigointiviestin kehys on samat tavut kaikilla alustoilla ja kaikissa käännösprofiileissa, WebAssembly (WASM) -käännös mukaan lukien	Kyllä	`src/portable_math.rs` (jokainen transkendenttifunktio ja jokainen normaalijakautunut poikkeama tyypissä `leo-navmsg` kulkee puhtaan Rust-paketin (crate) `libm` kautta); `leo_navmsg::tests::the_encoded_frame_is_the_same_bytes_on_every_platform` lukitsee kokonaisen kehyksen ilman alustarajausta
Siemenellä tehdyt indeksiarvonnat (bootstrap-uudelleenotanta, sekoitukset) ovat samat 32- ja 64-bittisillä kohteilla	Kyllä	`portable_math::uniform_index` otantaa aina tyyppinä `u64`; lukittu kohdassa `portable_math::tests`
Sama työkaluketju kaikkialla	Kyllä	`rust-toolchain.toml` lukitsee kanavan; `scripts/check-toolchain.sh` kaataa koontiversion poikkeaman sattuessa; CI ja julkaisu lukitsevat saman version
Sama riippuvuusjoukko	Kyllä	`Cargo.lock` on versionhallinnassa, ja `cargo metadata --locked` käytetään SBOM-luettelon (ohjelmistokomponenttiluettelo) tuottamiseen

Jokainen komentorivin ajo kirjoittaa raporttiinsa myös toistettavuustiedot (<scenario>.report.json ja .report.html): moottorin version, skenaariotiedoston ja tulosasiakirjan SHA-256-tiivisteen, siemenluvun, alustan ja tarkan komennon, jonka tests/advanced_report_cli.rs ajaa uudelleen tavu tavulta samaan tulokseen. Raportti on itsessään ajon puhdas funktio: kaksi ajoa skenaariosta scenarios/clock-holdover.toml kirjoittaa saman tiedoston report.json tavu tavulta. Katso REPORTS.md.

Alustojen välinen varauma (ja miten kultaiset vertailuarvot sen käsittelevät)#

Numeeriset tulokset ovat bitilleen samat yhdellä alustalla, mutta voivat poiketa muutamalla viimeisen numeron yksiköllä (ULP) alustojen välillä. Syynä on alustan matematiikkakirjasto: IEEE-754 (IEEE: Institute of Electrical and Electronics Engineers) ei vaadi funktioiden sqrt, ln, exp ja vastaavien oikeaa pyöristystä, joten Linux (glibc, GNU C -kirjasto), macOS ja Windows voivat kukin palauttaa eri viimeisen bitin. Pitkässä ajossa nämä ~1e-16 erot kertyvät suhteellisesti ehkä tasolle ~1e-12.

Kaksi asiaa suurentaa tuota viimeisen numeron eroa alkuperäisestä, ja molemmat on mitattu eikä oletettu. Mukautuva integraattori valitsee seuraavan askeleensa virhearviosta viidennen juuren kautta, joten yksi yksikkö viimeisessä numerossa muuttaa askelsarjaa, ja kaksi alustaa täsmäävät sitten vain integroinnin toleranssin tarkkuudella. Iteratiivinen estimaattori (pienimmän neliösumman sovitus, radanmääritysfiltteri) voi kulkea eri polkua suppenemiseen. Näihin perustuvat tyypit voivat poiketa alustojen välillä yli 1e-6 yksittäisissä kentissä; src/test_support.rs kirjaa saman tilanteen yksikkötesteille.

Käännösprofiili vaikuttaa samalla tavalla yhdellä koneella. Optimoitu käännös macOS:llä yhdistää yhden argumentin sinin ja kosinin yhdeksi kutsuksi järjestelmän yhdistettyyn rutiiniin, jonka sini poikkeaa yksinäisestä funktiosta sin viimeisessä bitissä 379 argumentille joukossa, jossa on 200 000 argumenttia; optimoimaton käännös tekee kaksi kutsua. Mitattuna aarch64-macOS:llä 138 skenaariotiedoston yli debug- ja release-käännös samasta lähteestä antavat tavu tavulta samat tulosasiakirjat 102 tiedostolla. Muiden 36 tiedoston tulokset poikkeavat viimeisissä numeroissa: 28 niistä enintään arvolla 1e-6, yksi (leo-ppp-convergence) määrällä 2.8e-6, ja seitsemän kampanjaa vain jäsenajojensa tiivisteissä; mikään ei poikkea merkinnässä, lukumäärässä tai tuomiossa. Tavu tavulta -takuu pätee siis yhdelle käännökselle: samalle binäärille kahdesti.

Siemenellä tehdyt normaalijakaumavedot ovat kolmas, paljon harvinaisempi lähde: otantafunktio kutsuu isännän eksponentti- ja logaritmifunktiota harvinaisissa haaroissaan, ja noin yksi veto miljoonasta poikkeaa viimeisessä bitissä natiivin ja WASM-käännöksen välillä.

Kun tuloste on diskreetti, viimeisen numeron ero ei ole lainkaan hyväksyttävä, ja tyyppi lasketaan isäntäkirjaston sijaan tiedoston src/portable_math.rs funktioilla. Tyyppi leo-navmsg on ensimmäinen: sen binäärikehys on lähetettyjä kokonaislukuja, ja sama skenaario koodattiin kerran kolmeksi eri kehykseksi: release-käännöksessä, saman lähteen debug-käännöksessä ja selaimessa. Nyt se on samat tavut kaikissa kolmessa.

Tämän vuoksi golden-testit eivät lukitse yhtä alustojen välistä tiivistettä liukulukutulosteesta — se olisi hauras ja kaataisi rehellisesti oikeita käännöksiä toisella käyttöjärjestelmällä. Sen sijaan:

tests/golden.rs lukitsee jokaisen laatumittarin suhteellisella toleranssilla 1e-6 — neljä suuruusluokkaa tiukemmin kuin mikään todellinen regressio (joka siirtää arvoa kokonaisilla prosenteilla), mutta paljon löysemmin kuin alustojen välinen matematiikkakirjaston (libm) värinä. Ruudukon rajaamat kentät (holdover-sekunnit) ja täsmälleen nolla -kentät lukitaan täsmälleen.
scenario_hash — syötteiden sisältötiiviste — on alustasta riippumaton ja lukittu täsmälleen.
tests/cross_platform_golden.rs lukitsee tarkan SHA-256-tiivisteen, tallennettuna skenaariokohtaisesti hakemistoon tests/golden/, projektiosta, joka on identtinen alustojen välillä: syötteen sormenjälki sekä tulosteen muoto (kenttien nimet, sisäkkäisyys, lehtityypit, taulukoiden pituudet — kiinteitä deterministisen ruudukkoaritmetiikan vuoksi, eivät koskaan liukulukuarvoja). Tämä saa rakenteelliset regressiot kiinni täsmälleen, kun yllä olevat toleranssilukitukset saavat arvoregressiot kiinni.
scripts/check-reproducible.sh varmistaa tavu tavulta saman tulosteen kahdessa ajossa samalla koneella (determinismitakuu).
CI-työ reproducibility-matrix ajaa neljä yllä olevaa testiä (cross_platform_golden, golden, determinism, sgp4_verification) alustoilla ubuntu-latest, macos-latest ja windows-latest, joten alustojen välinen toistettavuus varmistetaan jokaisella pushilla — muoto- ja syötevertailut täsmälleen, numeriikka tarkkuudella 1e-6 ja SGP4-tilat (Simplified General Perturbations 4) tarkkuudella 2e-5 km — yhteen käyttöjärjestelmään luottamisen sijaan.

Jos lukitut luvut täytyy luoda uudelleen (esim. tarkoituksellisen mallimuutoksen jälkeen), aja jokainen vertailuskenaario ja kopioi tulostetut FoM-arvot tiedostoon tests/golden.rs, ja kirjaa muutos tiedostoon CHANGELOG.md.

Ohjelmistokomponenttiluettelo (SBOM)#

scripts/gen-sbom.sh tuottaa CycloneDX-muotoisen (versio 1,5) SBOM-luettelon, joka listaa jokaisen kshana-artefaktissa toimitettavan paketin (crate) tarkkoine versioineen, lähteineen ja lisensseineen. Se on riippuvuudeton generaattori, joka perustuu komentoon cargo metadata --locked (joten se toimii pelkällä työkaluketjulla), ja se kulkee ratkaisugraafin kshana-paketista vain normaalien ja käännösriippuvuuksien kautta. Kehitysriippuvuudet (vain testeihin tarkoitetut paketit, kuten sgp4) jätetään pois, koska yksikään artefakti ei sisällä niitä.

Graafi on niiden ominaisuusjoukkojen yhdiste, joilla toimitettavat artefaktit rakennetaan: oletuskäännös (kirjasto ja komentoriviliittymä (CLI)), --features python (PyPI-wheel (PyPI: Python Package Index), jonka ketju pyo3 on sen vierasfunktiorajapinta) ja --features wasm (npm-paketti, joka kantaa saman SBOM-luettelon tarballinsa sisällä). Kaikkien kohteiden alustakohtaiset ehdolliset riippuvuudet ovat mukana, koska wheelit toimitetaan useille käyttöjärjestelmille ja npm-paketti kohdistuu WebAssemblyyn. Yksi asiakirja kattaa kaikki kolme artefaktia, joten yksittäiselle niistä se on ylijoukko. Se luettelee tällä hetkellä 107 komponenttia; lukumäärä on lukittu kohdassa tests/fixtures/reproducibility_software_assurance/. Erillisellä palvelimella kshana-mcp on oma manifestinsa, eikä tämä SBOM kuvaa sitä.

Tuloste on deterministinen — sama riippuvuusjoukko tuottaa tavu tavulta saman asiakirjan, myös sarjanumeron, joka johdetaan lajitellusta pakettiluettelosta eikä aikaleimasta.

Julkaisutyönkulku tuottaa SBOM-luettelon (kshana-sbom.cdx.json) ja liittää sen jokaiseen merkittyyn julkaisuun; jakelutyönkulku toimittaa sen myös PyPI-wheelien rinnalla ja npm-paketin sisällä.

Käännöksen alkuperätiedot#

Julkaisutyönkulku tuottaa SLSA (Supply-chain Levels for Software Artifacts) -käännösalkuperätodistuksen (actions/attest-build-provenance), joka kattaa jokaisen GitHub-julkaisuun liitetyn tiedoston: komentorivibinäärit kullekin alustalle, palvelinbinääri kshana-mcp, SBOM, validointiyhteenveto ja SHA256SUMS. Käyttäjä voi komennolla gh attestation verify todentaa, että artefaktit on rakennettu tämän repositorion julkaisutyönkulussa tästä lähteestä — sulkien aukon sanojen ”tässä on binääri” ja ”tässä on binääri, jonka voin jäljittää lähteeseensä” väliltä. Esimerkiksi SBOM-luettelolle versiossa 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