h5i-app-pgsql 0.5.5

PostgreSQL text for h5i-app's planned statements; extracted to Lean and proven to mean what the planner's statements mean
Documentation

h5i-app

A Rust application framework for h5i. Write application logic in Rust and prove its properties in Lean 4.

Crates.io

[dependencies]
h5i-app = { version = "0.5", features = ["http", "postgres"] }
Crate Role
h5i-app feature-gated entry point for web and database integrations
h5i-app-core the Kernel contract and an in-memory reference engine
h5i-app-http Axum integration: Actor, H5iApp::respond, rpc_router
h5i-app-pg the PostgreSQL engine
h5i-app-schema schema!: row types, table mappings, generated Lean
h5i-app-sql write sets to keyed SQL statements (extracted, proven)
h5i-app-pgsql statements to PostgreSQL text (extracted, proven)
h5i-app-json the reply JSON writer (extracted, proven)
h5i-app-token bearer-token encoding and parsing (extracted, proven)
h5i-app-std extractable kernel utilities and reusable verified authorization guards
h5i-app-h1 no_std, heap-free HTTP/1.1 parsing and framing (extracted, proven)
h5i-app-embedded async, heap-free HTTP server for embedded kernels
h5i-app-gpu optional batch execution adapters with CPU fallback and differential checks

Kernel crates depend directly on the extractable components they use, so extraction does not pull in Axum or PostgreSQL drivers. Embedded and GPU support are separate crates, not h5i-app feature flags.

High level features

  • Write application logic as pure Rust functions and prove custom properties in Lean 4 via Aeneas.
  • Reuse verified components and generic guarantees, including authorization guards and storage compilation.
  • Serve kernels with Axum or an async no_std embedded HTTP server.
  • Run web requests in SERIALIZABLE PostgreSQL transactions, with retries and idempotency keys.
  • Declare tables once with schema! to generate Rust mappings and Lean proof artifacts.
  • Optionally accelerate eligible batch workloads on GPUs, with CPU fallback and differential testing.

The Axum/PostgreSQL path separates extracted logic from trusted infrastructure:

flowchart LR
    H["HTTP transport: axum, hyper (trusted)"] --> K["kernel (extracted)"]
    K --> S["storage: plan, SQL compiler (extracted)"]
    S --> DB["engine, PostgreSQL (trusted)"]

    K -. Aeneas .-> A["application-specific proofs"]
    S -. Aeneas .-> B["framework-provided proofs"]
    DB -. "SQL model" .-> B
    SP["Spec (reviewed)"] --> A
    A --> D["db_inv"]
    B --> D

Usage example

The kernel is one function that decides what a command does. This one, from the calculator tutorial, keeps one number per user:

pub fn transition(actor: &Principal, snap: &Snapshot, cmd: &Command) -> Result<(Option<Memory>, Reply), Error> {
    match cmd {
        Command::Set { value } => Ok((Some(Memory { user: actor.user, value: *value }), Reply::Value(*value))),
        Command::Apply { op, arg } => {
            let m = memory_of(&snap.memories, actor.user);
            match compute(*op, m, *arg) {
                Ok(v) => Ok((Some(Memory { user: actor.user, value: v }), Reply::Value(v))),
                Err(e) => Err(e),
            }
        }
        Command::Get => Ok((None, Reply::Value(memory_of(&snap.memories, actor.user)))),
    }
}

The server around it is an ordinary Axum application:

let engine = Arc::new(Engine::<Calc, CalcStore>::new(pool(&url, 8)?, EngineConfig::default()));
engine.install_schema().await?;
let app = H5iApp::new(engine, HmacAuth::<Calc>::new(secret, principal));
let router = Router::new().route("/healthz", get(|| async { "ok" })).merge(rpc_router(app));
axum::serve(TcpListener::bind("127.0.0.1:8080").await?, router).await?;

pool connects over plain TCP. For certificate-verified TLS to PostgreSQL, enable the tls feature and use pool_tls with Roots::WebPki or Roots::PemFile(ca). For the full trust boundary and assumptions, see what h5i-app proves and assumes.

After the kernel is translated to Lean, you can prove properties of it, for example that after any successful command a get by the same user returns its result:

theorem get_after (a : Principal) (s s' : Snapshot) (c : Command) (w : Option Memory) (v : U64)
    (hroom : s.memories.length < Usize.max)
    (ht : transition a s c = ok (.Ok (w, .Value v))) (hs : apply s w = ok s') :
    transition a s' .Get = ok (.Ok (none, .Value v))

License

This project is licensed under the Apache-2.0 license.