Skip to content

Developer-Guide.md

Latest commit

 

History

History
260 lines (180 loc) · 7.44 KB

Developer-Guide.md

File metadata and controls

260 lines (180 loc) · 7.44 KB

Developer Guide

This guide defines the development workflow and release gates for Axiom.jl.

Prerequisites

  • Julia 1.10+
  • Git
  • Optional for backend work:
    • Zig toolchain
    • CUDA / ROCm / Metal runtimes

Local Setup

cd Axiom.jl
julia --project=. -e 'using Pkg; Pkg.instantiate()'

Build and Test

Run the full baseline pipeline before merging:

julia --project=. -e 'using Pkg; Pkg.build(); Pkg.precompile(); Pkg.test()'

One-Command Readiness Gate

Run the consolidated release-readiness checks:

./scripts/readiness-check.sh

Useful toggles:

  • AXIOM_READINESS_RUN_ZIG=0 disables Zig parity/smoke checks.
  • AXIOM_READINESS_RUN_COPROCESSOR=0 disables coprocessor strategy/resilience checks.
  • AXIOM_READINESS_RUN_GPU_PERF=0 disables GPU resilience/performance evidence checks.
  • AXIOM_READINESS_RUN_COULD_PACKAGING=0 disables model package/registry could-item checks.
  • AXIOM_READINESS_RUN_COULD_OPTIMIZATION=0 disables optimization-pass could-item checks.
  • AXIOM_READINESS_RUN_COULD_TELEMETRY=0 disables verification-telemetry could-item checks.
  • AXIOM_READINESS_ALLOW_SKIPS=1 allows skipped checks without failing the run.
  • AXIOM_COPROCESSOR_SELF_HEAL=0 disables coprocessor self-healing fallback (useful for failure-path testing).
  • AXIOM_TPU_REQUIRED=1 enforces strict TPU mode (no compile/runtime fallback).
  • AXIOM_NPU_REQUIRED=1 enforces strict NPU mode (no compile/runtime fallback).
  • AXIOM_DSP_REQUIRED=1 enforces strict DSP mode (no compile/runtime fallback).
  • AXIOM_MATH_REQUIRED=1 enforces strict MATH mode (no compile/runtime fallback).
  • AXIOM_COPROCESSOR_REQUIRED=1 enforces strict mode for all coprocessor backends unless backend-specific flags override.
  • JULIA_BIN=/path/to/julia selects a specific Julia binary.

Runtime Smoke Tests

Run quick runtime checks after unit tests:

julia --project=. test/ci/runtime_smoke.jl

Backend Parity (CPU vs Zig)

Run parity checks when Zig backend is available:

cd zig && zig build -Doptimize=ReleaseFast
AXIOM_ZIG_LIB=$PWD/zig/zig-out/lib/libaxiom_zig.so julia --project=. test/ci/backend_parity.jl

Tolerance budgets used by CI parity checks:

  • matmul: atol=1e-4, rtol=1e-4
  • dense: atol=1e-4, rtol=1e-4
  • conv2d: atol=2e-4, rtol=2e-4
  • normalization: atol=1e-4, rtol=1e-4
  • activations: atol=1e-5, rtol=1e-5

GPU Fallback and Hardware Smoke

Run explicit fallback checks (no GPU required):

julia --project=. test/ci/gpu_fallback.jl

Run hardware smoke checks on GPU runners:

AXIOM_GPU_BACKEND=cuda AXIOM_GPU_REQUIRED=1 julia --project=. test/ci/gpu_hardware_smoke.jl
AXIOM_GPU_BACKEND=rocm AXIOM_GPU_REQUIRED=1 julia --project=. test/ci/gpu_hardware_smoke.jl
AXIOM_GPU_BACKEND=metal AXIOM_GPU_REQUIRED=1 julia --project=. test/ci/gpu_hardware_smoke.jl

Run GPU resilience diagnostics and generate machine-readable baseline evidence:

julia --project=. test/ci/gpu_resilience.jl
julia --project=. scripts/gpu-performance-evidence.jl

Generate backend-specific evidence on dedicated hardware runners:

AXIOM_GPU_BASELINE_BACKEND=cuda AXIOM_GPU_REQUIRED=1 julia --project=. scripts/gpu-performance-evidence.jl
AXIOM_GPU_BASELINE_BACKEND=rocm AXIOM_GPU_REQUIRED=1 julia --project=. scripts/gpu-performance-evidence.jl
AXIOM_GPU_BASELINE_BACKEND=metal AXIOM_GPU_REQUIRED=1 julia --project=. scripts/gpu-performance-evidence.jl

scripts/gpu-performance-evidence.jl reads optional thresholds from:

  • AXIOM_GPU_BASELINE_PATH (default: benchmark/gpu_performance_baseline.json)
  • AXIOM_GPU_BASELINE_ENFORCE (set to 1 to fail on regressions vs baseline)
  • AXIOM_GPU_MAX_REGRESSION_RATIO (default: 1.20)

Non-GPU Coprocessor Strategy

Run deterministic strategy/fallback checks for TPU/NPU/PPU/MATH/FPGA/DSP targets:

julia --project=. test/ci/coprocessor_strategy.jl

Generate a machine-readable capability/evidence artifact:

julia --project=. scripts/coprocessor-evidence.jl

Run coprocessor resilience diagnostics (self-healing + fault-tolerance counters):

julia --project=. test/ci/coprocessor_resilience.jl

Generate coprocessor resilience evidence artifact:

julia --project=. scripts/coprocessor-resilience-evidence.jl

Could: Model Packaging + Registry

Run packaging/registry workflow checks:

julia --project=. test/ci/model_package_registry.jl

Generate machine-readable package/registry evidence artifacts:

julia --project=. scripts/model-package-evidence.jl

Could: Optimization Pass Evidence

Run optimization pass behavior checks:

julia --project=. test/ci/optimization_passes.jl

Generate optimization benchmark/drift evidence:

julia --project=. scripts/optimization-evidence.jl

Could: Verification Telemetry

Run structured telemetry coverage checks:

julia --project=. test/ci/verification_telemetry.jl

Generate verification telemetry evidence artifact:

julia --project=. scripts/verification-telemetry-evidence.jl

TPU/NPU/DSP/MATH Strict Mode (Production Gate)

Run strict-mode behavior checks for TPU/NPU/DSP/MATH fallback blocking and hook requirements:

julia --project=. test/ci/tpu_required_mode.jl
julia --project=. test/ci/npu_required_mode.jl
julia --project=. test/ci/dsp_required_mode.jl
julia --project=. test/ci/math_required_mode.jl

Generate machine-readable TPU/NPU/DSP/MATH strict-mode evidence:

julia --project=. scripts/tpu-strict-evidence.jl
julia --project=. scripts/npu-strict-evidence.jl
julia --project=. scripts/dsp-strict-evidence.jl
julia --project=. scripts/math-strict-evidence.jl

Use templates/AxiomTPUExtSkeleton.jl, templates/AxiomNPUExtSkeleton.jl, templates/AxiomDSPExtSkeleton.jl, and templates/AxiomMathExtSkeleton.jl as starters for extension hook overrides.

Certificate Integrity Checks

Run certificate reproducibility and tamper-detection checks:

julia --project=. test/ci/certificate_integrity.jl

Proof-Assistant Bundle Reconciliation

When Lean/Coq/Isabelle artifacts are updated, reconcile manifest status:

julia --project=. -e 'using Axiom; reconcile_proof_bundle("build/proofs/my_model.obligations.json")'

Run deterministic CI reconciliation coverage:

julia --project=. test/ci/proof_bundle_reconciliation.jl

Generate proof bundle evidence for CI artifacts/review:

julia --project=. scripts/proof-bundle-evidence.jl

Quality Gates

Use these checks to keep production paths clean:

rg -n "TO[D]O|FIXM[E]|TB[D]|OPEN_ITEM|FIX_ITEM|XXX|HACK" src test ext

If a marker is required (for templates or roadmap planning), keep it out of production code paths (src, ext, test) and explain it in review notes.

Documentation Expectations

  • User-facing behavior changes require updates in:
    • docs/wiki/User-Guide.md
    • docs/wiki/Home.md
  • Developer workflow changes require updates in:
    • docs/wiki/Developer-Guide.md
  • Claims in README/wiki must match tested behavior.

Release Checklist

  1. Pkg.build, Pkg.precompile, and Pkg.test pass on a clean environment.
  2. Runtime smoke checks pass.
  3. No unresolved production work-marker markers in src, ext, or test.
  4. CPU vs Zig parity and certificate integrity CI checks pass.
  5. README/wiki claims are aligned with actual implementation status.
  6. Version metadata is consistent (Project.toml and Axiom.VERSION).