################################################################################################
#            ____              _   _                ____        __      _                      #
#           |  _ \ _   _ _ __ | |_(_)_ __ ___   ___/ ___|  __ _/ _| ___| |_ _   _              #
#           | |_) | | | | '_ \| __| | '_ ` _ \ / _ \___ \ / _` | |_ / _ \ __| | | |            #
#           |  _ <| |_| | | | | |_| | | | | | |  __/___) | (_| |  _|  __/ |_| |_| |            #
#           |_| \_\\__,_|_| |_|\__|_|_| |_| |_|\___|____/ \__,_|_|  \___|\__|\__, |            #
#                                                                             |___/            #
################################################################################################

Lean-based runtime kernels engineered for reliability, auditability, and deterministic validation.

The project focuses on safety-critical runtime behavior across policy, concurrency, and shape handling, with strict documentation-to-gate alignment.

---

Why This Repository Exists

Runtime systems fail in production when guarantees are implicit, tests are brittle, or builds are environment-sensitive.
This repository hardens that path by making reliability properties explicit and mechanically checkable.

Reliability Guarantees

• Canonical contracts: shared runtime-critical aliases live in src/RuntimeSafetyKernels/Contracts.lean.
• Proof-hole enforcement: safety-critical modules must stay free of sorry, enforced by python scripts/check_proof_completeness.py.
• Contract consistency: extraction paths are checked by python scripts/check_contract_consistency.py.
• Resilient execution: validation runs with diagnostics, retry/backoff, and fallback runtime checks for unstable environments.

Quick Start

Run the full local reliability pipeline:

python scripts/validate_local.py

This command orchestrates diagnostics, gate checks, build, and runtime verification through a primary path plus fallback path where needed.

Windows (CreateProcess error 87)

Mathlib-heavy exe links can exceed the Windows argv limit. One-command toolchain setup, then use the resilient wrapper:

python scripts/install_leanc_rsp_shim.py install
python scripts/lake_resilient.py -- lake build

lake_resilient.py installs the shim when possible and auto-relinks via scripts/windows_relink_exes.py after link failures. Status: python scripts/install_leanc_rsp_shim.py status.

Build and Validation Tooling

Tool	Purpose	Output/Behavior
scripts/lake_doctor.py	Environment, toolchain, and TLS/network diagnostics	Writes build/lake-diagnostics.json
scripts/lake_resilient.py	Execute lake with retry/backoff; on Windows, rsp-relink after CreateProcess error 87	Preferred entry for lake update / lake build
scripts/install_leanc_rsp_shim.py	One-command Windows leanc @rsp shim install/uninstall/status	Rewrites long argv before real leanc
scripts/windows_relink_exes.py	Relink mathlib-heavy exes via Clang @rsp when Lake's argv is too long	Used automatically by lake_resilient.py on Windows
scripts/run_runtime_checks.py	Run tests, fuzz, benchmarks	Windows: relink retry then lake env lean --run fallback
scripts/validate_local.py	Orchestrate full local validation	Runs primary sequence, then fallback sequence on failure

Project Entry Points

• Main module: src/RuntimeSafetyKernels.lean
• Tests: src/RuntimeSafetyKernels/Tests.lean
• Fuzz checks: src/RuntimeSafetyKernels/Fuzz.lean
• Benchmarks: src/RuntimeSafetyKernels/Benchmarks.lean
• Canonical contracts: src/RuntimeSafetyKernels/Contracts.lean

Fallback Lean runners used by runtime checks:

• src/RuntimeSafetyKernels/Runner/TestsMain.lean
• src/RuntimeSafetyKernels/Runner/FuzzMain.lean
• src/RuntimeSafetyKernels/Runner/BenchmarksMain.lean

Documentation Map

• API surface: docs/api.md
• Capability matrix (status, tests, fuzz, cost, exclusions): docs/capability-matrix.md
• Contribution standards: CONTRIBUTING.md

Contribution Expectations

All changes are expected to preserve reliability guarantees, provide verification evidence, and keep documentation aligned with implementation reality.