diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index c83dbad9..3cca063c 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -7,13 +7,13 @@ The README makes claims. This file backs them up. == Claims Substantiation -=== Claim 1: "Mathematically proven safe operations. Code that cannot crash, verified with Idris2 dependent types and totality checking." +=== Claim 1: "Safe operations written in Idris2, with dependent types and totality checking." (goal: code that cannot crash) -**How it works:** The 104 core safety modules in `src/Proven/` are written in Idris2 with `%default total`, meaning every function is proved to: (1) terminate (no infinite loops), (2) cover all input cases (no pattern match exceptions), and (3) return a value (no throwing runtime exceptions). Dependent types encode preconditions as types (e.g., `SafeDiv : (a : Nat) -> (b : Nat) -> (h : NonZero b) -> Nat` requires a proof that `b` is nonzero before dividing). The Idris2 compiler enforces these proofs at compile time. Examples: `SafeMath.rs` proves arithmetic never overflows (returns `Result` or bounded nat); `SafeString.rs` proves buffer bounds are checked before reading. FFI bindings call these verified functions only—no reimplementation in other languages. +**How it works:** The core safety modules in `src/Proven/` are written in Idris2, most with `%default total`. A `total` function is checked to (1) terminate and (2) cover all input cases, so it (3) returns a value. **Not every module meets that bar** (measured 2026-11-17, comments excluded): 4 modules use `%default covering` (`SafeJson/Access`, `SafeBase64`, `SafeBase64/Encode`, `SafeRBAC`), 66 functions in 14 files are marked `covering`, and 22 `assert_total`/`assert_smaller` sites in 7 modules (`SafeArgs/Parser`, `SafeInput`, `SafeRegex/Matcher`, `SafeTree`, `SafeUnionFind`, `SafeXML/Parser`, `SafeYAML/Parser`) bypass the totality checker. Those are not totality-proven. Dependent types encode preconditions as types (e.g., `SafeDiv : (a : Nat) -> (b : Nat) -> (h : NonZero b) -> Nat` requires a proof that `b` is nonzero before dividing). The Idris2 compiler enforces these proofs at compile time. Examples: `SafeMath.idr` returns `Maybe`/bounded results instead of overflowing; `SafeString.idr` checks buffer bounds before reading. FFI bindings call these verified functions only—no reimplementation in other languages. -**Caveat:** Verification covers correctness (no crashes, no undefined behavior), not functional correctness (the algorithm might be wrong). Also, Idris2 proved code is only safe if the FFI bridge (`ffi/zig/`) correctly marshals data. If Zig FFI incorrectly casts types or ignores preconditions, safety claims are violated. Hypatia scans prove this doesn't happen (0 unsafe patterns in critical FFI code). +**Caveat:** For functions the totality checker accepts as `total`, without an `assert_total` or `assert_smaller` escape hatch, Idris2 establishes termination and coverage of every input case, plus the preconditions written into the types. It does not establish this for the `covering` code and escape-hatch sites listed above, and it does not establish functional correctness (the algorithm might still be wrong). The FFI bridge (`ffi/zig/`) is outside the Idris2 check: the Idris2 guarantees hold only if it marshals data correctly. If Zig FFI incorrectly casts types or ignores preconditions, safety claims are violated. Hypatia scans report 0 unsafe patterns in critical FFI code; a scan is evidence, not a proof. -**Evidence:** `src/Proven/SafeMath.idr` with `%default total` and dependent type proofs; `src/Proven/SafeString.idr` with bounds-checked buffer operations. FFI in `ffi/zig/src/main.zig` calls verified functions only. Test suite: 49 tests passing, 0 believe_me count (eliminated via ADR-008). +**Evidence:** `src/Proven/SafeMath.idr` with `%default total` and dependent type proofs; `src/Proven/SafeString.idr` with bounds-checked buffer operations. FFI in `ffi/zig/src/main.zig` calls verified functions only. `believe_me` count: 0 (eliminated via ADR-008). The test suite did not build at the link:AFFIRMATION.adoc[AFFIRMATION] anchor; see its "What we do NOT claim". === Claim 2: "120+ binding targets across 4 computing paradigms without reimplementing logic" @@ -41,7 +41,7 @@ The README makes claims. This file backs them up. |=== | Path | Purpose -| `src/Proven/` | Idris2 core (THE TRUTH): 104 modules, all with `%default total` +| `src/Proven/` | Idris2 core (THE TRUTH): 104 modules, most with `%default total` (4 use `%default covering`; see Claim 1) | `src/Proven/SafeMath.idr` | Arithmetic proofs: overflow-safe add/sub/mul/div, bounded nat, checked operations | `src/Proven/SafeString.idr` | String buffer bounds, encoding safety, slicing without panics | `src/Proven/SafeFloat.idr` | Floating-point proofs: no NaN, denormal, infinity handling, comparison stability @@ -54,7 +54,7 @@ The README makes claims. This file backs them up. | `ffi/zig/` | C ABI bridge layer | `ffi/zig/src/main.zig` | Wraps Idris2 RefC output, exposes C functions for each Safe* module | `ffi/zig/build.zig` | Builds Idris2 code to .o files, links with Zig, outputs shared library -| `bindings/` | Language-specific thin wrappers (18 complete, 102 scaffolded) +| `bindings/` | Language-specific thin wrappers (16 complete, 102 scaffolded) | `bindings/rust/` | Rust bindings: safe_*.rs files call proven FFI via unsafe { } | `bindings/rust/safe_math.rs` | Wraps proven_ffi_safe_add, proven_ffi_safe_mul, etc. | `bindings/zig/src/` | Zig language binding (calls FFI directly; necessarily Zig) @@ -75,4 +75,4 @@ The README makes claims. This file backs them up. == Readiness -**CRG Grade:** C (Beta) - Core modules proven (0 believe_me, 104 modules), Rust/Python/C bindings complete and tested (18 targets), remaining 102 targets scaffolded and awaiting completion. Production-ready for Rust/Python/C; others are research-stage. +**CRG Grade:** C (Beta) - Core modules implemented with 0 `believe_me` (104 modules); not all are totality-proven (22 `assert_total`/`assert_smaller` sites, 4 `%default covering` modules; see Claim 1), and AFFIRMATION.adoc does not affirm "mathematically proven". 16 binding targets complete (the Python/Cython and ReScript bindings were deleted; the 16 are the TOPOLOGY.adoc list, not re-measured), remaining 102 targets scaffolded and awaiting completion. Rust and C are the production focus; others are research-stage. diff --git a/README.adoc b/README.adoc index c71d4c5f..a58e1b4f 100644 --- a/README.adoc +++ b/README.adoc @@ -1,12 +1,12 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -= proven: Formally Verified Safety via Idris2 += proven: Safe Operations in Idris2 with Dependent Types :toc: macro :toclevels: 2 :icons: font :source-highlighter: rouge -*Mathematically proven safe operations.* Code that **cannot crash**, verified with Idris2 dependent types and totality checking. +*Safe operations written in Idris2, with dependent types and totality checking.* The goal is code that **cannot crash**. That is not yet proven for the whole library: some modules still use totality escape hatches, listed in <>. image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/proven"] image:https://img.shields.io/badge/version-1.2.0-blue[Version 1.2.0] @@ -14,8 +14,9 @@ image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[MPL-2.0,link="https image:https://img.shields.io/badge/modules-104-blue[104 Modules] image:https://img.shields.io/badge/bindings-120+_targets-orange[120+ Binding Targets] image:https://img.shields.io/badge/verified-Idris_2-purple[Verified with Idris 2] -image:https://img.shields.io/badge/believe__me-0_✓-brightgreen[believe_me = 0 (fully eliminated)] -image:https://img.shields.io/badge/overall-55%25-yellow[Overall 55%] +image:https://img.shields.io/badge/believe__me-0-brightgreen[believe_me = 0] +image:https://img.shields.io/badge/assert__total%20%2B%20assert__smaller-22-orange[22 assert_total/assert_smaller sites] +image:https://img.shields.io/badge/bindings-16_of_120+_complete-yellow[16 of 120+ binding targets complete] image:https://api.thegreenwebfoundation.org/greencheckimage/jewell.nexus[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=jewell.nexus"] == License @@ -25,7 +26,7 @@ This project is licensed under **MPL-2.0**. See link:LICENSE[LICENSE]. == What Makes proven Different? *Traditional Libraries:* Trust the author got it right + -*proven:* **Mathematical proof** the code cannot crash +*proven:* The type checker enforces totality and the stated invariants, except where the escape hatches listed in <> remain === Architecture @@ -131,19 +132,27 @@ only. Any non‑Idris safety logic in bindings is being removed or rewritten. | Core Modules | 104 -| Idris 2 verified implementations (258 total .idr files including FFI wrappers) +| Idris 2 implementations, totality-checked except as listed in <> (802 `.idr` files in the repository, counted 2026-11-17) | Binding Targets | 120+ -| Languages, platforms, and paradigms (18 complete, 102 scaffolded) +| Languages, platforms, and paradigms (16 complete, 102 scaffolded) | believe_me Count | 0 | Eliminated from ~4,566 instances (remediated 2026-02-22) -| Overall Completion -| ~55% -| Core solid (100%), apps (7%), hardware (0%), convenience (0%) +| assert_total / assert_smaller +| 22 +| 20 + 2 non-comment sites in 7 modules; they bypass the totality checker (see <>) + +| `%default covering` modules +| 4 +| Not totality-checked by default + +| Completion +| 16 of 120+ binding targets +| 102 targets are scaffolded with FFI stubs; apps, hardware and convenience layers are early (see link:TOPOLOGY.adoc[TOPOLOGY.adoc]) |=== === Binding Categories @@ -226,7 +235,7 @@ Every one of these will crash your app or create a security hole. ---- from proven import SafeMath, SafeJson, SafeUrl, SafePassword, SafeRegex, SafeHtml, SafeCommand, SafeSql -# Cannot crash. Ever. Mathematically proven. +# Design goal: no exceptions. Totality-checked only where the module is `total` (see Proof status). result = SafeMath.div(10, user_input) # Returns None if zero, not an exception data = SafeJson.get(response, "key") # Returns None if missing, typed if present url = SafeUrl.parse(user_url) # Returns structured error or valid URL @@ -242,8 +251,21 @@ query = SafeSql.query("SELECT * FROM users WHERE name = ?", [user_input]) # SQL This isn’t marketing fluff. Here’s what makes proven different from regular libraries: * Every function in proven is written in Idris 2, a language with dependent types. -* The compiler literally proves your code is correct before it runs. -* All 104 core modules have verified implementations (believe_me=0 as of v1.2.0). 120+ binding targets exist (18 fully implemented, 102 scaffolded with FFI stubs). Overall project ~55% complete — see link:TOPOLOGY.md[TOPOLOGY.md] for full dashboard. +* The compiler checks every type. For a `total` function it also checks that the function terminates and covers every input. A function proves only what its type states. +* All 104 core modules have implementations with no `believe_me` (as of v1.2.0). They are not all totality-proven: see <>. 120+ binding targets exist (18 fully implemented, 102 scaffolded with FFI stubs); see link:TOPOLOGY.adoc[TOPOLOGY.adoc] for the full dashboard. + +[[proof-status]] +=== Status of the proofs + +Measured on 2026-11-17 by grep over `src/` (comment lines excluded). Status words follow standards `3-practice/PROOF-POLICY.adoc` §5: a module with an escape hatch is not `proven`. + +* *`believe_me`*: 0. +* *`assert_total` / `assert_smaller`*: 22 sites (20 + 2), which bypass the totality checker, in 7 modules: `SafeArgs/Parser`, `SafeInput`, `SafeRegex/Matcher`, `SafeTree`, `SafeUnionFind`, `SafeXML/Parser`, `SafeYAML/Parser`. +* *`%default covering`*: 4 modules, `SafeJson/Access`, `SafeBase64`, `SafeBase64/Encode` and `SafeRBAC`. Their functions are checked for coverage, not termination. +* *Functions marked `covering`*: 66, in 14 files (most in `SafeFiniteField`, `SafeHeap` and `SafeBitset`). +* *Proven theorems*: link:AFFIRMATION.adoc[AFFIRMATION.adoc] does not affirm "mathematically proven". Its sample found a discharged theorem in 1 of 32 modules. 79 `.idr` files under `src/` still list `OWED` obligations. + +So "cannot crash" is the design goal, not a proven property of the whole library. === Understanding Dependent Types (In 2 Minutes) @@ -273,16 +295,16 @@ This is the core insight: instead of runtime crashes, we get compile-time errors [cols="1,1"] |=== -| Regular Code | Proven Code +| Regular Code | Proven Code (where a function is `total` with no escape hatch; see <>) | "I think this won’t crash" -| "The compiler proved this cannot crash" +| "The compiler checked that this terminates and handles every input" | "I tested it and it worked" -| "Every possible input was checked at compile time" +| "Every input case is covered, checked at compile time" | "It passed code review" -| "A theorem prover verified it" +| "The Idris2 type checker accepted its types (named theorems: see AFFIRMATION.adoc)" |=== === Want to Learn More? @@ -1818,10 +1840,10 @@ Notable additions beyond traditional languages: ┌─────────────────────────────────────────────────────────────────┐ │ Idris 2 Verified Core (v1.1.0) │ │ │ -│ • 104 modules with dependent types: compiler PROVES code │ -│ is correct │ -│ • Total functions: every input produces valid output │ -│ • No runtime exceptions: impossible by construction │ +│ • 104 modules with dependent types; the compiler checks the │ +│ stated types, not full functional correctness │ +│ • `total` functions terminate and cover every input │ +│ • Escape hatches remain in 7 modules (see Proof status) │ │ • ECHIDNA integration for CI verification │ │ │ │ Used by: aerospace, automotive, financial, blockchain │ @@ -1849,7 +1871,7 @@ If you find a bug in proven, you’ve likely found a bug in either: 1. The language bindings (our bug, please report) 2. The Idris 2 compiler (extremely rare) 3. Your understanding of the function (check the docs) -The core logic is mathematically proven. But the bindings are written by humans. +The core logic is type-checked, and totality-checked where it is `total` (see <>). The bindings are written by humans. Q: Why not just use existing libraries?:: [cols="1,1"] @@ -1873,7 +1895,7 @@ Q: Why not just use existing libraries?:: |=== Q: Is this production ready?:: -Yes, as of v1.0.0. All core modules and bindings are complete. Security audit passed, comprehensive test suite, and ECHIDNA integration for proof verification. +Partly. The Idris2 core modules are implemented, with the totality limits listed in <>. Of the 120+ binding targets, 16 are complete and 102 are scaffolds that are not ready for use. Rust and C are the production focus; the other bindings are research-stage. Check the status table before choosing a binding for production. Q: I'm using Rust... isn't my code invincible anyway? @@ -1925,7 +1947,7 @@ Crashes are a choice. Choose otherwise. === v1.0.0 * ✅ Initial release with 74 core modules and dependent type proofs -* 120+ binding targets via Zig FFI (18 complete, 102 scaffolded) +* 120+ binding targets via Zig FFI (16 complete, 102 scaffolded) * ✅ Complete test suite with fuzzing * ✅ Security audit passed * ✅ CI/CD infrastructure diff --git a/TOPOLOGY.adoc b/TOPOLOGY.adoc index eb7a8a46..8f673d9d 100644 --- a/TOPOLOGY.adoc +++ b/TOPOLOGY.adoc @@ -66,11 +66,11 @@ └────────────────┬────────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ - │ LANGUAGE BINDINGS (15%) │ + │ LANGUAGE BINDINGS (16 of 120) │ │ (Thin Wrappers — FFI Calls Only) │ │ │ - │ ✅ Complete (18): Python, Rust, JavaScript, Deno, │ - │ ReScript, Gleam, Julia, Swift, Kotlin, Go, Elixir, │ + │ ✅ Complete (16): Rust, JavaScript, Deno, Gleam, │ + │ Julia, Swift, Kotlin, Go, Elixir, │ │ Zig, Lua, Ruby, Nim, OCaml, Haskell, Ada │ │ │ │ ░░ Scaffolded (102): C, C++, Erlang, Dart, Java, │ @@ -104,12 +104,12 @@ CORE MODULES (IDRIS2) VERIFICATION ECHIDNA Integration ██████████ 100% ProofTerm + Validator + Soundness - Totality Checking ██████████ 100% --total flag enforced + Totality Checking not complete 4 %default covering modules, 22 assert_total/assert_smaller sites (README Proof status) believe_me Count ██████████ 100% 0 instances (was 4,566) BRIDGE & BINDINGS Zig FFI Bridge ██████████ 100% 65 exports, stable C ABI - Bindings Complete ██░░░░░░░░ 15% 18/120 fully implemented + Bindings Complete █░░░░░░░░░ 13% 16/120 fully implemented (list not re-measured) Bindings Scaffolded █████████░ 85% 102/120 have FFI stubs APPLICATIONS