Skip to content

GUIDESTONE.md

Latest commit

 

History

History
255 lines (196 loc) · 13 KB

GUIDESTONE.md

File metadata and controls

255 lines (196 loc) · 13 KB

guideStone Certification — hotSpring-guideStone-v0.7.0

Artifact: Chuna Engine + Validation Suite Standard: GUIDESTONE_STANDARD.md v1.0 Date: 2026-03-31 Certification: Self-assessed per Sovereign Science principle

Property 1: Deterministic Output

  • Same binary produces same results on x86_64
  • Same binary produces same results on aarch64 (CI target — cross-compiler needed)
  • CPU-only path produces full validation results (59/59 checks)
  • GPU auto-detected: parity checks run per-adapter when f64 GPU present
  • CPU-GPU plaquette parity verified within 1e-10 (f64 rounding)
  • CPU-GPU energy density parity verified within 1e-8 (accumulated integration)
  • Cross-GPU agreement verified (NVIDIA vs AMD: same tolerances as CPU-GPU)
  • No environment-dependent behavior (no locale, timezone, or hostname in physics output)
  • Tested on x86_64 Linux (pop-os, kernel 6.17.9)
  • Tested on NVIDIA RTX 3090 (--gpus Docker passthrough)
  • Tested on AMD RX 6950 XT (/dev/dri Docker passthrough)
  • Multi-substrate Docker validation: CPU-only, NVIDIA, AMD, both GPUs
  • aarch64 cross-arch testing (CI target)

Cross-substrate tolerance derivations (from finite-precision error model):

Observable Tolerance Derivation
Plaquette (CPU-GPU) 1e-10 abs Double-precision arithmetic on identical gauge config; GPU parallelism reorders partial sums
Energy density (CPU-GPU) 1e-8 rel Accumulated flow integration; 200 RK3 steps × O(ε_mach) per step
Dielectric functions 1e-12 abs Simple arithmetic, no stochastic noise
Cross-GPU (NVIDIA vs AMD) Same as CPU-GPU Both GPUs are f64-capable; DF64 emulation adds ≤2 ULP

Status: Complete for x86_64 + dual GPU; aarch64 = CI target

Property 2: Reference-Traceable

  • Every numeric output traces to a paper, standard, or proof
  • References are machine-readable in JSON output (paper field per check)
  • No orphan numbers — every value has provenance
  • Every binary embeds a RunManifest in its JSON output (timestamp, hostname, argv, git commit, engine version, GPU)
  • ImplementationInfo::auto_detect() discovers GPU adapters and embeds git commit hash
  • Optional --telemetry=<path> JSONL sidecar for streaming observables (per-trajectory, per-config)
  • Validation matrix produces timestamped output files (run_<ts>.json) with latest.json symlink

Papers validated against:

Paper Citation Checks
43 Bazavov & Chuna, arXiv:2101.05320 Gradient flow: integrator convergence, energy smoothing, t2E monotonicity, t0/w0 scale setting, LSCFRK3 W7 efficiency
44 Chuna & Murillo, Phys. Rev. E 111, 035206 BGK dielectric: plasma dispersion, Kramers-Kronig, f-sum rules, conductivity, DSF, Mermin/completed models
45 Haack et al., J. Comput. Phys. (2024), DOI:10.1016/j.jcp.2024.112908 Kinetic-fluid coupling: BGK relaxation conservation, Sod shock tube, coupled simulation stability

Status: Complete — 59/59 checks carry paper citations

Property 3: Self-Verifying

  • CHECKSUMS file present (SHA-256, all artifact files)
  • CHECKSUMS validated before execution (./run, ./chuna-engine)
  • Tampered input detected and reported (non-zero exit on mismatch)
  • ILDG CRC on gauge configuration data payloads (via chuna_convert --verify)

Status: Complete

Property 4: Environment-Agnostic

  • ecoBin compliant by default: Pure Rust dependency graph from hotSpring (no direct libc); hardware BAR0 probes (Exp 070) are behind the low-level Cargo feature (optional rustix syscalls). Static musl / cross-arch remain targets for release binaries.
  • No runtime dependencies (no downloads, no package managers)
  • No sudo required
  • CPU-only mode covers full validation output (59/59 checks)
  • No hardcoded paths or platform assumptions
  • Binary reports detected substrate to the user
  • No GPU required for validation
  • No network required
  • aarch64 binary included (pending cross-compilation CI)

Binaries (all static-pie ELF, x86_64-unknown-linux-musl):

Binary Source Size Purpose
validate-x86_64 validate_chuna ~652K Paper 43/44/45 validation suite
validation-matrix-x86_64 validation_matrix ~740K Extended validation matrix
chuna-generate-x86_64 chuna_generate ~716K ILDG gauge config generation
chuna-flow-x86_64 chuna_flow ~652K Gradient flow analysis
chuna-measure-x86_64 chuna_measure ~664K Observable measurement suite
chuna-convert-x86_64 chuna_convert ~640K ILDG/LIME/QCDml conversion
chuna-benchmark-flow-x86_64 chuna_benchmark_flow ~644K Integrator efficiency workbench
chuna-matrix-x86_64 chuna_matrix ~952K Task matrix orchestration

Status: Complete for x86_64, aarch64 = CI target

Property 5: Tolerance-Documented

  • Every tolerance has a derivation in the output metadata (tolerance_justification field)
  • Derivations are physical/mathematical (convergence hierarchy, conservation laws, sum rules, analytical limits)
  • Domain experts can audit the justification (JSON output is self-documenting)
  • No magic numbers

Example tolerance derivations from output:

Check Tolerance Justification
gradient_flow_integrator_convergence exact |RK2-RK3| < |Euler-RK3| (convergence hierarchy)
gradient_flow_energy_smoothing exact E(t_final) <= E(t_initial) under flow
plasma_dispersion_imaginary_zero 1e-10 Im[W(0)]=0 exact (real argument)
f_sum_rule_mermin 0.1 Kramers-Kronig sum rule: integral of Im[ε]/ω = -π/2 ωp²
bgk_mass_conservation 1e-8 BGK collision conserves mass exactly
sod_mass_conservation 0.02 Sod shock tube: mass conserved to discretization order

Status: Complete

Cross-Substrate Parity (Python / Rust CPU / Rust GPU)

Three independent implementations of the same physics, each validated against the others. This is the strongest reproducibility guarantee: the result doesn't depend on the implementation language or hardware.

Per-Paper Tolerance Table

Paper Observable Python vs Rust CPU Rust CPU vs GPU Derivation
6 Eigenvalues (z/kappa/l) 1e-10 abs — (CPU eigensolve) Sturm bisection vs scipy on same tridiagonal
6 Critical screening kappa 1e-3 abs — Threshold sensitivity to grid resolution
8 Plaquette (per beta) 5e-3 abs 1e-10 abs Thermalization noise on 4^4, 30 traj
8 Polyakov loop 0.1 abs 0.05 abs Large fluctuations on small volume
9 Plaquette (beta-scan) 5e-3 abs 1e-10 abs Same as Paper 8 across full scan
9 Monotonicity exact exact Both must show plaquette monotone in beta
10 Dynamical plaquette 5e-3 abs 1e-10 abs Thermalization + CG noise on 4^4
11 HVP integral sign exact exact Must be positive in all substrates
11 C(t) positivity exact exact Correlator >= 0 for all time slices
11 Mass ordering exact exact Lighter quarks give larger HVP
12 beta_c location 0.3 abs 0.1 abs Finite-volume crossover on 4^4
12 Plaquette monotone exact exact Both must see monotone

(beta)
12 Transition detected exact exact Polyakov must jump near beta_c
13 Plaquette (per config) 5e-2 abs 1e-10 abs HMC noise on small (1+1)D lattice
13 Higgs condensate 5e-2 abs 1e-10 abs Scalar field fluctuations
43 Plaquette (beta=6.0) 1e-4 abs 1e-10 abs Thermalization noise on 8^4; GPU reorders partial sums
43 Flow energy density 1e-6 abs 1e-8 rel RK integration error at eps=0.01; GPU accumulation order
43 Convergence order (W6/W7/CK4) 0.5 abs N/A (CPU only) Finite-size suppression on small lattice
43 Scale setting (t0, w0) 0.1 abs 0.01 abs Scale setting on small lattice; statistical noise
44 Standard Mermin 1e-8 abs 1e-12 abs Analytic form; quadrature agreement
44 Completed Mermin 1e-5 abs 1e-10 abs Completed form is quadrature-sensitive
44 f-sum rule 1e-6 abs 1e-10 abs Integral of Im[eps]/omega
44 Conductivity 1e-4 abs 1e-8 abs Drude-like fit sensitivity
45 Conservation (mass/momentum/energy) 1e-10 abs 1e-12 abs Exact conservation in both implementations
45 Shock position (N=200) 1e-3 abs 1e-4 abs Grid-resolution dependent
45 H-theorem (entropy monotonicity) 1e-8 abs 1e-10 abs Entropy non-decrease is physical law

Substrate Inventory

Substrate Papers Covered Entry Point
Python Control 24/25 control/*/scripts/*_control.py
Rust CPU 25/25 cargo run --release --bin validate_chuna_overnight
Rust GPU 20/25 --gpu flag on chuna_generate, GPU shaders via toadStool

Validation Mode

  • compare_substrates.py automates Python-vs-Rust parity checking (10 papers: 6, 8-13, 43-45)
  • run_all_parity.py orchestrates full paper-queue green board (74 checks, 9/9 active papers)
  • Tolerances are physically derived per observable (no magic numbers)
  • HOTSPRING_NO_PYTHON=1 skips Python substrate (pure Rust validation)
  • HOTSPRING_NO_GPU=1 skips GPU substrate (pure CPU validation)
  • All chuna_* binaries default to CPU when --gpu is not passed
  • chuna_validate_shader accepts --no-gpu for CPU-only shader validation
  • validation/run --three-substrate calls run_all_parity.py for full 10-paper suite

Status: Complete — all three substrates validated across full paper queue (9/9 active ALL GREEN)

NUCLEUS Layer (Optional — additive provenance)

All NUCLEUS features are runtime-detected and degrade gracefully when primals are absent. The bare guideStone (Properties 1-5 above) works standalone on any machine. When running inside a NUCLEUS deployment, the following capabilities are activated:

bearDog Signing

  • Receipt carries Ed25519 detached signature when bearDog is present
  • receipt_signing.rs sends crypto.sign JSON-RPC with 2s timeout
  • .sig file written alongside JSON receipt
  • Signature fields (signature, signer_public_key) embedded in receipt
  • Graceful skip when bearDog is absent (no signature fields, no error)

rhizoCrypt DAG Provenance

  • Computation trace with merkle root when rhizoCrypt is present
  • dag_provenance.rs creates session, appends per-phase events, dehydrates
  • DAG events include: phase name, wall time, observable summary
  • dag_session_id and merkle_root embedded in RunManifest.nucleus
  • Graceful skip when rhizoCrypt is absent (no DAG fields)

toadStool Integration

  • Silicon performance surface reported via compute.performance_surface.report
  • compute.capability_query queries NUCLEUS-wide GPU inventory
  • Falls back to local GpuF64::enumerate_adapters() when toadStool absent
  • compute.shader.register available for validated shader absorption

Primal Discovery

  • NucleusContext::detect() probes all primal sockets at startup
  • HOTSPRING_NO_NUCLEUS=1 env var skips all primal detection
  • Banner prints discovered primals (same pattern as GPU discovery)
  • All chuna_* binaries wire NUCLEUS context into RunManifest

Graceful Degradation

  • All NUCLEUS features are additive — no behavioral change to physics
  • Bare guideStone Properties 1-5 fully satisfied without any primals
  • Binary produces identical physics output with or without NUCLEUS
  • NUCLEUS metadata is skip_serializing_if = "Option::is_none"

Overall Certification

Property Status
1. Deterministic Complete (x86_64 + NVIDIA + AMD; aarch64 = CI)
2. Reference-Traceable Complete
3. Self-Verifying Complete
4. Environment-Agnostic Complete for x86_64
5. Tolerance-Documented Complete
Cross-Substrate Parity Complete — 10 papers, 74 checks, 9/9 active ALL GREEN
NUCLEUS: bearDog Signing Wired — activates when bearDog present
NUCLEUS: rhizoCrypt DAG Wired — activates when rhizoCrypt present
NUCLEUS: toadStool Integration Wired — reporting + capability query + shader register
NUCLEUS: Graceful Degradation Complete — all features optional

Certification Level: guideStone-ready for x86_64 with multi-GPU parity. Full cross-arch certification requires aarch64 CI pipeline. NUCLEUS provenance layer wired and degrades gracefully.

Artifact Name: hotSpring-guideStone-v0.7.0 Composition: Spring guideStone (validation/run) + Composition guideStone (chuna-engine)

Validation Scripts:

  • scripts/validate-guidestone-multi.sh — hotSpring-side Docker orchestration (4 substrates)
  • benchScale/scripts/validate-hotspring-multi.sh — benchScale-side with hardware profile extraction + cross-substrate comparison matrix