Reproduceerbaarheid en herkomst

Kshana is gebouwd om reproduceerbaar te zijn: dezelfde invoer levert dezelfde resultaten, en de buildartefacten zijn terug te voeren op de bron die ze heeft voortgebracht. Dit document vermeldt precies wat wordt gegarandeerd, wat niet, en hoe de garanties worden afgedwongen.

Determinismegaranties#

De engine kent geen systeemklok, geen afhankelijkheid van de uitvoeringsthread en geen ongezaaide willekeur. Elk stochastisch proces wordt aangedreven door een ChaCha8Rng-stroom die door de seed van het scenario wordt gesleuteld en in vaste volgorde wordt getrokken. Gevolgen:

Elke run vanaf de opdrachtregel schrijft ook een reproduceerbaarheidsverslag in zijn rapport (<scenario>.report.json en .report.html): de engineversie, de SHA-256 van het scenariobestand en van het resultaatdocument, de seed, het platform en de exacte opdracht, die tests/advanced_report_cli.rs opnieuw uitvoert tot een byte-identiek resultaat. Het rapport is zelf een zuivere functie van de run: twee runs van scenarios/clock-holdover.toml schrijven dezelfde report.json byte voor byte. Zie REPORTS.md.

Het voorbehoud over platforms (en hoe goldens ermee omgaan)#

De numerieke resultaten zijn bitidentiek op een gegeven platform maar kunnen tussen platforms in de laatste paar eenheden van de laatste plaats (ULP) verschillen. De oorzaak is de wiskundebibliotheek van het platform: sqrt, ln, exp en verwante functies hoeven volgens IEEE-754 (IEEE: Institute of Electrical and Electronics Engineers) niet correct afgerond te zijn, zodat Linux (glibc, de GNU C library), macOS en Windows elk een andere laatste bit kunnen teruggeven. Over een lange run lopen deze verschillen van ~1e-16 op tot misschien ~1e-12 relatief.

Twee dingen maken dat verschil in de laatste plaats groter dan het begint, en beide zijn gemeten en niet aangenomen. Een adaptieve integrator kiest zijn volgende stap uit de foutschatting via een vijfdemachtswortel, zodat één eenheid in de laatste plaats de stapvolgorde verandert en de twee platforms dan alleen nog overeenkomen tot de integratietolerantie. Een iteratieve schatter (een kleinstekwadratenfit, een filter voor baanbepaling) kan een ander pad naar convergentie nemen. Soorten die op een van beide steunen kunnen tussen platforms in afzonderlijke velden met meer dan 1e-6 verschillen; src/test_support.rs legt hetzelfde regime voor de unittests vast.

Het buildprofiel speelt op dezelfde manier een rol, op één machine. Een geoptimaliseerde build op macOS voegt een sinus en een cosinus van één argument samen tot één aanroep van de gecombineerde routine van het systeem, waarvan de sinus voor 379 van 200.000 argumenten in de laatste bit afwijkt van de losse sin; een niet-geoptimaliseerde build doet de twee aanroepen. Gemeten op aarch64 macOS over de 138 scenariobestanden geven een debug- en een releasebuild van één bron voor 102 byte-identieke resultaatdocumenten. De overige 36 verschillen in de laatste plaatsen: 28 binnen 1e-6, één (leo-ppp-convergence) met 2.8e-6, en zeven campagnes alleen in de digests van hun ledenruns; geen enkele verschilt in een label, een aantal of een verdict. De garantie van byte-identiteit hierboven geldt dus voor één build: dezelfde binary tweemaal.

De gezaaide normale trekkingen vormen een derde, veel zeldzamere bron: de sampler roept in zijn zeldzame takken de exponentiële en logaritmische functie van de host aan, en ongeveer één trekking op een miljoen verschilt in de laatste bit tussen de native build en de WASM-build.

Waar een uitvoer discreet is, is een verschil in de laatste plaats helemaal niet acceptabel, en wordt de soort berekend met src/portable_math.rs in plaats van met de hostbibliotheek. De soort leo-navmsg is de eerste: haar binaire frame bestaat uit verzonden gehele getallen, en hetzelfde scenario werd eens gecodeerd tot drie verschillende frames: in een releasebuild, in een debugbuild van dezelfde bron, en in de browser. Het zijn nu in alle drie dezelfde bytes.

Daarom leggen de golden tests niet één platformoverschrijdende hash van de uitvoer met drijvende komma vast — dat zou fragiel zijn en zou eerlijk correcte builds op een ander OS laten mislukken. In plaats daarvan:

• tests/golden.rs legt elke kwaliteitsmaat vast met een relatieve tolerantie van 1e-6 — vier ordes van grootte strakker dan elke echte regressie (die een waarde met hele procenten verschuift) maar veel ruimer dan de jitter van de wiskundebibliotheek (libm) tussen platforms. Velden begrensd door het raster (holdover-seconden) en velden die exact nul zijn, worden exact vastgelegd.
• scenario_hash — een inhoudshash van de invoer — is platformonafhankelijk en wordt exact vastgelegd.
• tests/cross_platform_golden.rs legt een exacte SHA-256 vast, per scenario vastgelegd in tests/golden/, over de projectie die wél identiek is over platforms: de invoervingerafdruk plus de vorm van de uitvoer (veldnamen, nesting, bladtypen, arraylengten — vastgelegd door deterministische rasterrekenkunde, nooit de waarden met drijvende komma). Dit vangt structurele regressies exact op, terwijl de toleranties hierboven waardenregressies opvangen.
• scripts/check-reproducible.sh dwingt byte-identieke uitvoer af over twee runs op dezelfde machine (de determinismegarantie).
• De CI-job reproducibility-matrix voert de vier tests hierboven uit (cross_platform_golden, golden, determinism, sgp4_verification) op ubuntu-latest, macos-latest en windows-latest, zodat platformoverschrijdende reproduceerbaarheid bij elke push wordt vastgesteld — de vorm-/invoergoldens exact, de numerieke waarden tot 1e-6, en de SGP4-toestanden (Simplified General Perturbations 4) tot 2e-5 km — in plaats van op één enkel OS te vertrouwen.

Als u de vastgelegde getallen opnieuw moet genereren (bijvoorbeeld na een opzettelijke modelwijziging), voer dan elk referentiescenario uit en kopieer de afgedrukte FoM-waarden naar tests/golden.rs, en noteer de wijziging in CHANGELOG.md.

Software bill of materials (SBOM)#

scripts/gen-sbom.sh genereert een CycloneDX 1,5-SBOM met elke crate die in een kshana-artefact wordt meegeleverd, met haar exacte versie, bron en licentie. Het is een generator zonder afhankelijkheden, gebouwd op cargo metadata --locked (zodat hij met alleen de toolchain werkt), en hij doorloopt de resolutiegraaf vanaf het kshana-pakket via alleen normale afhankelijkheden en build-afhankelijkheden. Dev-afhankelijkheden (crates alleen voor tests, zoals sgp4) zijn uitgesloten omdat geen enkel artefact ze bevat.

De graaf is de vereniging van de featuresets waarmee de meegeleverde artefacten worden gebouwd: de standaardbuild (bibliotheek en opdrachtregelinterface (CLI)), --features python (het PyPI-wheel (Python Package Index), waarvan de keten pyo3 zijn foreign-function-grens is) en --features wasm (het npm-pakket, dat dezelfde SBOM in zijn tarball meedraagt). Platformvoorwaardelijke afhankelijkheden voor elk doel zijn inbegrepen, omdat de wheels voor meerdere besturingssystemen worden geleverd en het npm-pakket op WebAssembly mikt. Eén document dekt alle drie de artefacten, dus voor elk afzonderlijk is het een superset. Het vermeldt momenteel 107 componenten; het aantal is vastgelegd in tests/fixtures/reproducibility_software_assurance/. De losstaande server kshana-mcp heeft zijn eigen manifest en wordt door deze SBOM niet beschreven.

De uitvoer is deterministisch — dezelfde set afhankelijkheden levert een byte-identiek document op, met een serienummer dat is afgeleid van de gesorteerde pakketlijst in plaats van van een tijdstempel.

De releaseworkflow genereert de SBOM (kshana-sbom.cdx.json) en voegt die toe aan elke getagde release; de publicatieworkflow levert hem ook mee naast de PyPI-wheels en in het npm-pakket.

Herkomst van de build#

De releaseworkflow produceert een SLSA (Supply-chain Levels for Software Artifacts)-attestatie van de buildherkomst (actions/attest-build-provenance) die elk bestand dekt dat hij aan de GitHub Release toevoegt: de opdrachtregelbinaries voor elk platform, de serverbinary kshana-mcp, de SBOM, de validatiesamenvatting en SHA256SUMS. Een gebruiker kan met gh attestation verify verifiëren dat de artefacten zijn gebouwd door de releaseworkflow van deze repository uit deze bron — waarmee de kloof wordt gedicht tussen "hier is een binary" en "hier is een binary die ik naar zijn bron kan herleiden". Bijvoorbeeld voor de SBOM van 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