Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions EXPLAINME.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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.
70 changes: 46 additions & 24 deletions README.adoc
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
// 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 <<proof-status>>.

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]
image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[MPL-2.0,link="https://github.com/hyperpolymath/proven/blob/main/LICENSE"]
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
Expand All @@ -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 <<proof-status>> remain

=== Architecture

Expand Down Expand Up @@ -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 <<proof-status>> (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 <<proof-status>>)

| `%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
Expand Down Expand Up @@ -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
Expand All @@ -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 <<proof-status>>. 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)

Expand Down Expand Up @@ -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 <<proof-status>>)

| "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?
Expand Down Expand Up @@ -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 │
Expand Down Expand Up @@ -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 <<proof-status>>). The bindings are written by humans.

Q: Why not just use existing libraries?::
[cols="1,1"]
Expand All @@ -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 <<proof-status>>. 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?

Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions TOPOLOGY.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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, │
Expand Down Expand Up @@ -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
Expand Down
Loading