Reproducerbarhed og proveniens

Kshana er bygget til at kunne reproduceres: de samme input giver de samme resultater, og buildartefakterne kan spores tilbage til den kilde, der frembragte dem. Dette dokument angiver præcist, hvad der garanteres, hvad der ikke garanteres, og hvordan garantierne håndhæves.

Determinismegarantier#

Motoren har intet vægur, ingen afhængighed af tråden for udførelsen og ingen frøløs tilfældighed. Hver stokastisk proces drives af en ChaCha8Rng-strøm, der er nøglet til scenariets seed og trukket i en fast rækkefølge. Konsekvenser:

Hver kørsel fra kommandolinjen skriver også en reproducerbarhedsoptegnelse ind i sin rapport (<scenario>.report.json og .report.html): motorversionen, SHA-256 af scenariefilen og af resultatdokumentet, seed, platformen og den præcise kommando, som tests/advanced_report_cli.rs genkører til et byte-identisk resultat. Rapporten er selv en ren funktion af kørslen: to kørsler af scenarios/clock-holdover.toml skriver den samme report.json byte for byte. Se REPORTS.md.

Forbeholdet om tværplatform (og hvordan golden-filer håndterer det)#

De numeriske resultater er bit-identiske på en given platform, men kan afvige i de sidste få enheder på sidste plads (ULP) mellem platforme. Årsagen er platformens matematikbibliotek: sqrt, ln, exp og lignende kræves ikke af IEEE-754 (IEEE: Institute of Electrical and Electronics Engineers) at være korrekt afrundet, så Linux (glibc, GNU C-biblioteket), macOS og Windows kan hver returnere en forskellig sidste bit. I en lang kørsel akkumuleres disse forskelle på ~1e-16 til måske ~1e-12 relativt.

To ting gør denne forskel på sidste plads større, end den begynder, og begge er målt og ikke antaget. En adaptiv integrator vælger sit næste trin ud fra fejlskønnet gennem en femte rod, så én enhed på sidste plads ændrer trinfølgen, og de to platforme stemmer derefter kun overens til integrationstolerancen. En iterativ estimator (en mindste kvadraters tilpasning, et filter til banebestemmelse) kan tage en anden vej til konvergens. Typer bygget på en af dem kan afvige mellem platforme med mere end 1e-6 i enkelte felter; src/test_support.rs registrerer det samme område for enhedstestene.

Buildprofilen betyder det samme på én maskine. Et optimeret build på macOS slår en sinus og en cosinus af ét argument sammen til ét kald af systemets kombinerede rutine, hvis sinus afviger fra den enkeltstående sin i den sidste bit for 379 af 200.000 argumenter; et uoptimeret build foretager de to kald. Målt på aarch64 macOS over de 138 scenariefiler giver et debug- og et release-build af den samme kilde byte-identiske resultatdokumenter for 102. De øvrige 36 afviger på de sidste pladser: 28 inden for 1e-6, ét (leo-ppp-convergence) med 2.8e-6, og syv kampagner kun i digest af deres medlemskørsler; ingen afviger i en mærkat, et antal eller en afgørelse. Garantien om byte-identitet ovenfor gælder derfor for ét build: den samme binære fil to gange.

De seedede normalfordelte trækninger er en tredje, langt sjældnere kilde: samplerens kald af værtens eksponentialfunktion og logaritme i dens sjældne grene betyder, at omkring én trækning ud af en million afviger i den sidste bit mellem det native og WASM-buildet.

Hvor et output er diskret, er en forskel på sidste plads slet ikke acceptabel, og typen beregnes med src/portable_math.rs i stedet for værtsbiblioteket. Typen leo-navmsg er den første: dens binære ramme er sendte heltal, og det samme scenarie blev engang kodet til tre forskellige rammer: i et release-build, i et debug-build af den samme kilde og i browseren. Nu er det de samme bytes i alle tre.

Derfor fastlåser golden-testene ikke én enkelt hash på tværs af platforme af flydende-komma-outputtet — det ville være skrøbeligt og ville få korrekte builds til at fejle på et andet OS. I stedet:

• tests/golden.rs fastlåser hvert kvalitetsmål med en relativ tolerance på 1e-6 — fire størrelsesordener strammere end enhver reel regression (som flytter en værdi med hele procenter), men langt løsere end udsving i matematikbiblioteket (libm) på tværs af platforme. Felter, der er begrænset af gitteret (holdover-sekunder), og felter, der er nøjagtigt nul, fastlåses præcist.
• scenario_hash — en indholdshash af inputtene — er uafhængig af platform og fastlåst præcist.
• tests/cross_platform_golden.rs fastlåser en præcis SHA-256, committet for hvert scenarie i tests/golden/, over den projektion, der er identisk på tværs af platforme: inputfingeraftrykket plus outputtets form (feltnavne, indlejring, bladtyper, arraylængder — fastlagt af deterministisk gitteraritmetik, aldrig af flydende-komma-værdierne). Det fanger strukturelle regressioner præcist, mens toleranceloftet ovenfor fanger regressioner i værdier.
• scripts/check-reproducible.sh håndhæver byte-identisk output over to kørsler på den samme maskine (determinismegarantien).
• CI-jobbet reproducibility-matrix kører de fire ovenstående tests (cross_platform_golden, golden, determinism, sgp4_verification) på ubuntu-latest, macos-latest og windows-latest, så reproducerbarhed på tværs af platforme bekræftes ved hvert push — form- og input-golden-filerne præcist, numerikken til 1e-6 og SGP4 (Simplified General Perturbations 4)-tilstandene til 2e-5 km — i stedet for at bygge på ét enkelt OS.

Hvis du skal regenerere de fastlåste tal (for eksempel efter en tilsigtet modelændring), kør hvert referencescenarie og kopiér de udskrevne FoM-værdier ind i tests/golden.rs, og notér derefter ændringen i CHANGELOG.md.

Software bill of materials (SBOM)#

scripts/gen-sbom.sh udsender en CycloneDX 1,5-SBOM, der opregner hvert crate, som følger med i en kshana-artefakt, med dets præcise version, kilde og licens. Det er en afhængighedsfri generator bygget på cargo metadata --locked (så den virker med kun værktøjskæden), og den gennemløber opløsningsgrafen fra kshana-pakken kun gennem almindelige afhængigheder og build-afhængigheder. Udviklingsafhængigheder (crates, der kun bruges til test, som sgp4) er udeladt, fordi ingen artefakt indeholder dem.

Grafen er foreningsmængden af de featuresæt, som de udleverede artefakter bygges med: standardbuildet (biblioteket og CLI (kommandolinjegrænseflade)), --features python (PyPI (Python Package Index)-wheel, hvis pyo3-kæde er dets grænse til fremmede funktioner) og --features wasm (npm-pakken, som bærer den samme SBOM i sin tarball). Platformsbetingede afhængigheder for hvert mål er medtaget, da wheels udleveres til flere operativsystemer, og npm-pakken har WebAssembly som mål. Ét dokument dækker alle tre artefakter, så for en enkelt af dem er det en overmængde. Det opregner i øjeblikket 107 komponenter; antallet er fastlåst i tests/fixtures/reproducibility_software_assurance/. Den selvstændige kshana-mcp-server har sit eget manifest og er ikke beskrevet af denne SBOM.

Outputtet er deterministisk — det samme afhængighedssæt giver et byte-identisk dokument, herunder et serienummer udledt af den sorterede pakkeliste i stedet for af et tidsstempel.

Udgivelsesworkflowet genererer SBOM'en (kshana-sbom.cdx.json) og vedhæfter den til hver mærket udgivelse; publiceringsworkflowet leverer den også sammen med PyPI-wheels og inde i npm-pakken.

Buildets proveniens#

Udgivelsesworkflowet frembringer en SLSA (Supply-chain Levels for Software Artifacts)-attestering af buildets proveniens (actions/attest-build-provenance), der dækker hver fil, det vedhæfter GitHub Release: kommandolinjebinærfilerne for hver platform, serverbinærfilen kshana-mcp, SBOM'en, valideringsoversigten og SHA256SUMS. En forbruger kan med gh attestation verify kontrollere, at artefakterne blev bygget af dette repositorys udgivelsesworkflow ud fra denne kilde — og dermed lukke hullet mellem "her er en binær fil" og "her er en binær fil, jeg kan spore til dens kilde". For eksempel for SBOM'en til 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