PDD Kit Turns Software Plans Into Formal Specifications and Verified Code
- Cargo
- Machine Learning
- Shipped
- Shipper
- Alex Lavaee, Matthai Philipose
- Readers
- 553
PDD Kit translates plain language requirements into Verus proofs and tests, helping teams check that code follows the agreed plan.


Make the plan enforceable
When coding agents produce tens of thousands of lines in a sitting, reviewing every line stops being a workable safety net. The more consequential question is whether the code does what the team agreed it should do. PDD Kit is built around a stronger answer than inspection alone: turn that agreement into a formal specification, then prove the code satisfies it for every input the specification covers.
That distinction matters because a plan is only useful as a contract if the implementation is held to it. An agent can drift from the plan and write tests that validate its own choices. A large test suite may pass while the software still misses the user’s request. Proofs can close part of that gap; tests remain necessary for behavior that formal verification can’t cover.
Formal methods have often demanded specialist knowledge and substantial effort. PDD Kit aims to make them usable in ordinary software work, including by engineers without a formal methods background. It works with people and coding agents to turn plain language intent into specifications in Verus, prove the code against the formalized requirements, and generate tests for the parts that must be trusted or checked empirically.
We tried the approach on Pet Store, a full-stack storefront built in Rust, inside GitHub Next’s Chopin planning environment. The focus was its login logic. Verus helped harden that code and uncovered existing bugs; the proof establishes the absence of login bugs relative to the written specification. The developer reviewed the intended behavior without reading the generated code line by line. That’s a notable shift in what review can mean, though the assurance still depends on whether the specification captures the right requirements.
From plain language to checked behavior
PDD Kit runs as a partner inside Chopin, a real-time, shared planning environment. Its workflow starts with a team reviewing intent in plain language. The kit asks clarifying questions, explains relevant code, and records decisions in an intent artifact that connects the request to formal specifications and tests. Requirements that can be formalized become Verus specifications; the remaining assumptions become informal specifications covered by tests.
Each result is labeled by the kind of evidence behind it. Formal verification is a mathematical proof that code meets its specification for every possible input. PDD Kit currently uses Verus, a proof language for Rust co-developed by Microsoft Research, Carnegie Mellon University, VMware Research, ETH Zurich, MPI-SWS, UNSW Sydney, the University of Texas at Austin, the University of Michigan, the University of British Columbia, the University of Wisconsin–Madison, and the Weizmann Institute of Science.
Empirical verification runs the program and observes its behavior. That includes unit and end-to-end tests, terminal automation, browser agents, and computer-use agents for tasks a browser can’t drive. These checks matter for code outside the proof, such as third-party cryptography libraries and user interfaces. A passing test is evidence about the inputs it tried; it isn’t a proof about every possible input.
The boundary between proved code and assumed behavior is the Trusted Computing Base, or TCB. PDD Kit makes that boundary visible and asks the developer to approve each trusted component. The distinction is useful: a proof can be strong while still resting on assumptions about databases, clocks, libraries, or requirements that were never written down.

PDD Kit is to formal methods roughly what Spec Kit is to Spec-Driven Development. Its broader idea is called Proof-Driven Development: use agents to help write both the formal specifications and the proofs that connect those specifications to code.
A practical test: Pet Store login
Pet Store is a full-stack application written in Rust. Its backend uses Axum and SQLite for inventory, promotions, orders, and checkout. The storefront is built with Leptos and compiled to WebAssembly. The application contains about 5,000 lines of Rust.
The demonstration focuses on login, though the same process can be applied to functional correctness across the app. PDD Kit recommends beginning with the most sensitive components and verifying incrementally. Authentication is a sensible starting point: a login flaw could expose a customer account or administrator controls.
The developer’s request in Chopin was deliberately brief: “Verify the login logic in backend/src/handlers/auth.rs.” The two requirements were that a user gets a token only with the right password, and that only admin accounts get admin tokens. PDD Kit’s job is to turn that rough request into behavior precise enough to check.
Step 1: Resolve ambiguity before implementation
Before changing code, PDD Kit’s planning workflow, pdd-plan, reads the relevant code and presents questions in a Decisions tab. When a question depends on implementation details, its card explains the goal, the parts involved, and the specific function, so the developer can answer without opening the source.

It’s a small wording difference with a real consequence. “A token only follows the right password” says a wrong password must not get a token. It doesn’t say a correct password must succeed. A login system that rejects everyone satisfies that one-way condition. The requirement also needs the reverse direction: a correct password should produce a token. Together, those conditions mean a token is issued if and only if the password is right. An agent could silently choose either interpretation; here, the developer makes the choice explicitly.
Step 2: Keep a readable map of intent
As the discussion develops, PDD Kit maintains a rough-work section at the top of the plan. It collects the login flow, what will be proved versus trusted, and a mental model where a diagram helps. For this example, the mental model is a ticket desk.

An intent map then links each requirement to the developer’s words, the decision that settled it, the relevant part of the formal specification, and its tests. The specification includes annotated Verus contract snippets so the developer can see how the written requirement translates into a checkable condition.


Step 3: Choose how much of the handler to prove
Before implementation, the team signs off on the plan. PDD Kit’s first proposal proved the central login decision—the account selection and password check—while leaving the surrounding handler trusted and tested. The developer wanted the proof to cover more. The handler awaits lookups and signs the token, so a refactor could introduce an error in that orchestration even if the core decision remained correct.

The developer chose an async specification for the handler itself, so the proof would cover the orchestration instead of treating it as trusted. That moved most of the login path into the proof. A new function, login_flow, carries the contract from the request fields through to the token or HTTP error. PDD Kit returned the revised plan for approval: broader proof coverage also changes the scope and the assumptions the team accepts.
Step 4: Mark the edge of the proof
Some login behavior sits beyond what the verifier can establish. The hashing in bcrypt, queries in sqlx, and signing in jsonwebtoken live in other crates. The current contents of SQLite and the time on the clock come from the outside world. The specification describes what happens if a login request completes; it says nothing about whether a query hangs or how long it takes. Nor can a proof decide whether an error message is helpful or a screen is clear. And any requirement left out of the specification remains outside the proof.
PDD Kit handles these limits by stating the trusted boundary directly. It wraps trusted components in small functions with assumed contracts, using Verus’s #[verifier::external_body] or external_fn_specification. The developer approves each assumption, and the plan includes a test for every assumed clause.
For this login flow, the developer approved six trusted pieces:
Customer::find_by_emailandAdmin::find_by_username: each successful lookup returns the matching row in its own table, or no row.check_password, a wrapper aroundbcrypt::verify: it errors only when bcrypt can’t read the stored hash, andOk(true)means the password is correct.generate_token: it signs exactly the supplied claims with the configured secret and returns a 500 if signing fails.expiry_from_now: it reads the clock and sets expiry exactly 24 hours later.database_error: it turns a failed lookup into the current 500 response with sqlx’s message.- The login handler shell: it unpacks the request and passes the fields to
login_flowunchanged.
A lookup can stay in its existing location while getting a contract from outside the verifier:
/// Looks up a customer by exact email.
/// Trusted, not proved: the SQL query runs in sqlx, which Verus cannot check.
/// Every customer promise of `login_flow` rests on it.
/// #[verifier::external_fn_specification]
/// pub async fn ex_customer_find_by_email(pool: &sqlx::SqlitePool, email: &str)
/// -> (r: Result
The clock wrapper uses #[verifier::external_body]. Verus relies on its ensures clause and does not inspect the function body.
The useful boundary in a verified login system is the one it states plainly: which behavior Verus proves, which behavior the team trusts, and which behavior the design leaves unspecified. That boundary matters more than a green “verified” label. For example, the clock wrapper below promises an expiry 86,400 seconds after its reading, but the clock itself sits outside the proof. Its out-of-range panic is also left unpromised, matching the current login behavior.
/// Reads the clock and computes a token's expiry 24 hours ahead.
/// Trusted, not proved: chrono's clock is outside the proof.
/// It panics if the time is out of range, as today's login does;
/// that panic is not promised against.
/// #[verifier::external_body]
/// pub fn expiry_from_now() -> (r: Expiry)
/// ensures
/// // The expiry is exactly 24 hours (86,400 seconds) after the clock reading.
/// r.exp as int == r.now as int + 86_400,
/// {
/// ...
/// }
Figure 7 makes that division visible. Verus proves the login core for every input. Human review accepts the trusted parts, and tests check them. Some behavior has no guarantee at all.

The next two figures turn that boundary into a review process. Each trusted function gets its own card: the clauses Verus assumes, the developer’s acceptance of those assumptions, and the promise that would fail if an assumption were false. The plan then assigns empirical checks to those clauses, using Given/When/Then scenarios before the tests have been written. A check stays marked planned until it runs; afterward, the record includes its command result and the commit tested.


check_password. Verus takes these two clauses on faith, so a person accepts them and two tests check them.
check_password, written before the test exists. The plan labels a passing test as evidence rather than proof.And the exclusions are specific: the login future is not guaranteed to finish; an out-of-range clock may panic; timing and attempt rates are outside the promises; and the specification says nothing about how other endpoints interpret roles.
What the team reviews
The team reviews the intent artifact: a plain-language rendering of the Verus contracts generated by PDD Kit. That’s a practical choice. The coding agent writes the proof, and Verus checks each step during the build; if even one clause could fail for one input, the build fails and identifies it. The proof itself needn’t be read line by line. People review the specification that the proof must satisfy.
Each function’s ensures block describes what must be true of its result for every possible input. Figure 11 breaks down one clause on login_flow: a returned token must correspond to a valid account, a matching password, valid token claims, and the same account’s ID and role.

That repeated account variable catches a wiring error that can look harmless when each operation is checked alone. Suppose a bug verifies Bob’s password but signs a token for Alice. Bob used his own correct password, and the token may be well formed; still, the clause fails because the password check and token must refer to the same account. That kind of connection is easy for a test suite to overlook.
The spec also needs to describe SQLite, bcrypt, and JWTs without executing them. It uses uninterpreted functions—names with no implementation—to model the database rows (customer_on_file(email) and admin_on_file(username)), bcrypt’s answer (bcrypt_verdict(password, hash)), and a token’s contents (token_claims(token, secret)). Verus knows no behavior for these functions beyond the trusted contracts defined elsewhere. The proof can establish that login handles whatever row the model supplies; a trusted lookup contract is what connects that model to the database.
/// The customers row the database holds for
/// exactly this email, if any, when login looks.
/// Left abstract: only `Customer::find_by_email`'s
/// trusted contract says what it is.
/// pub uninterp spec fn customer_on_file(email: Seq<char>) -> Option<customer>;
/// ...
/// /// What bcrypt says about `password` against a
/// /// stored `hash`: Some(true) when it is the password
/// /// the hash was made from, Some(false) when it is
/// /// not, None when bcrypt cannot read the hash.
/// /// Left abstract: its meaning is bcrypt's, taken on trust through `check_password`.
/// pub uninterp spec fn bcrypt_verdict(password: Seq<char>, hash: Seq<char>)
/// -> Option<bool>;
///
/// /// The password is the right one for the stored hash, by bcrypt's verdict.
/// pub open spec fn password_matches(password: Seq<char>, hash: Seq<char>) -> bool {
/// bcrypt_verdict(password, hash) == Some(true)
/// }
A separate mathematical definition, named_account(email, username), selects the customer row for a supplied email; if no email is supplied, it selects the admin row for a supplied username; otherwise it yields no account. This Rust-like expression is specification-only ghost code: Verus checks it, but the compiler removes it from the running program.
/// The account a login names: the customers row for
/// the email when one is sent (role "customer"),
/// otherwise the admins row for the username (role "admin"), otherwise none.
/// pub open spec fn named_account(email: Option<string>, username: Option<string>)
/// -> Option<namedaccount> {
/// match email {
/// Some(e) => match customer_on_file(e@) {
/// Some(c) => Some(NamedAccount {
/// id: c.id@, password_hash: c.password_hash@, role: customer_role() }),
/// None => None,
/// },
/// None => match username {
/// Some(u) => match admin_on_file(u@) {
/// Some(a) => Some(NamedAccount {
/// id: a.id@, password_hash: a.password_hash@, role: admin_role() }),
/// None => None,
/// },
/// None => None,
/// },
/// }
/// }

The developer’s two-sentence request, together with the “Both ways” decision, becomes eight clauses on login_flow. Four preserve the system’s existing refusals, keeping the storefront and current API tests working. The contract covers a missing identity returning today’s 400 message; successful tokens matching the named account, password, ID, and role; and the expected outcomes for valid credentials, absent accounts, wrong passwords, unreadable bcrypt hashes, and customer versus admin logins. Lookup or signing failures can still produce a 500 where the contract allows it.
The full specification is long, but its shape is readable: each clause states a condition and the result it permits. For example, a request with neither email nor username must return the existing bad request message. If the request names an account and the password matches, the function must return a token or an internal error. A missing account or wrong password yields unauthorized unless lookup fails; an unreadable hash yields an internal error. Successful admin tokens require an admin row found by username with no email supplied, while email logins carry the customer role.
The trusted boundary appears in the implementation contracts too. check_password has a body Verus does not verify; its contract links the function to bcrypt_verdict, the abstract model of bcrypt, which has no axioms:
The proof has a boundary
The login proof’s most consequential assumption sits at the password check. The Rust wrapper calls bcrypt, but Verus can’t verify bcrypt’s implementation. It therefore trusts the wrapper’s contract: bcrypt returns a readable verdict for a usable stored hash, and that verdict correctly says whether the password matches. Every password guarantee inlogin_flow depends on that assumption.


Small contracts make the flow tractable
login_flow can stay short because it relies on smaller functions with their own contracts. lookup_target sends an email search to the customers table, gives email precedence when both identifiers are supplied, and uses the admins table for a username when no email is supplied. If neither is present, it reports a missing identity. decide_login refuses a missing account with the same Unauthorized result used for a wrong password, and returns claims only when a found row’s password hash matches. Successful claims carry the role associated with the selected table: admin for an admin lookup, customer for a customer lookup.
Verus proves the flow using those contracts, without reopening each function’s implementation. Change decide_login, and that function needs to be proved again; the larger flow can rely on its unchanged contract.
The file also marks what the proof can see. The database pool is opaque: the lookup contracts describe what searches return. A customer row exposes its fields to the proof. And LoginError separates the reason for refusal from the HTTP response: missing identity maps to 400, an absent account or wrong password to 401, and an unreadable bcrypt hash or database failure to 500.

From an approved spec to a checked build
Once the developer approves the specification, the build plan turns it into seven tasks: getlogin.rs compiling under Verus inside the backend crate, prove the decision logic, token issuance, and full flow, then test the trusted wrappers and run end-to-end login tests.

login.rs build under Verus while preserving every contract; if that can’t be done, the task asks for a decision instead of weakening the promise.What “fully verified” covers
After the tasks pass,pdd-prove opens pull requests for a verified/ crate containing login_flow, its component functions, their proofs, and tested trusted wrappers. The production handler is routed through that verified logic while retaining the existing HTTP status codes.
The proof covers the bodies of login_flow, login_core, lookup_target, decide_login, and issue_token against their contracts for every input. Those contracts specify how the flow selects an account table, checks the supplied password against the selected account’s stored hash, issues a token with that account’s ID and role, and refuses other cases with the current 400, 401, or 500 response and no token.
Other pieces remain trusted assumptions, though they’re tested: the two database lookups, bcrypt’s password check, the clock, token signing, database error messages, and the handler’s unpacking of the request. The claimed guarantees also depend on Verus, the Rust compiler, Z3, and Verus’s standard library, vstd (opens in new tab). Z3 is part of the assumed toolchain: Z3 (opens in new tab).
The team’s review shifts toward the intent artifact: people decide what the system should promise, while machines check whether the code and proof meet that promise. The pull request records which requirements are formally proved and which are checked empirically. After merge, CI runs Verus alongside the empirical tests, so later changes must continue satisfying the same spec. Tests that merely repeat a proved property can be pruned; tests for trusted boundaries remain.