Skip to the yard
Waxsealai

PDD Kit Turns Software Plans Into Formal Specifications and Verified Code

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.

PDD Kit Turns Software Plans Into Formal Specifications and Verified Code
PDDKit decision flowchart on green gradient background

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.

Flow diagram showing the PDD Kit workflow for formally verifying agent-written code. Team members review intent by expressing requirements in plain language, which are formalized in a pdd-plan containing decision cards, intent artifacts, trusted boundaries, and reviewer approvals. The plan generates a formal specification with Verus ensures clauses. Machines then check the code through pdd-prove, which includes Verus proofs, tests for trusted components, and LLM gap review. Verified code and receipts are submitted as a pull request. Dashed feedback loops return specification contradictions and verification gaps to earlier planning and coding stages.
Figure 1. Proof-Driven Development with PDD Kit: the team settles intent, then Verus and tests check the implementation against it.

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.

Screenshot of a verification tool evaluating a login authentication requirement. The prompt asks, “Must the right password always get a token?” A flow diagram shows a login request leading to a password check, where matching passwords receive a token and non-matching passwords are refused. Option A, highlighted as recommended, proves both outcomes: the correct password receives a token and an incorrect password is refused. Option B proves only that incorrect passwords are refused, leaving the result for the correct password unspecified.
Figure 2. “Only with the right password” permits a system that refuses every login. Requiring both outcomes rules out that reading.

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.

Three-panel illustration comparing login outcomes. In the first panel, a customer logs in with the correct email and password and receives a “customer” ticket. In the second panel, the same email is paired with an incorrect password and access is refused. In the third panel, an administrator logs in with the correct username and password and receives an “admin” ticket. The diagram uses a ticket-counter analogy to explain authentication and role-based access.
Figure 3. The login model: the submitted field selects a window, the window selects a table and role, and a ticket is issued only after the password matches.

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.

Intent map showing the login authentication flow for issuing a token. If an account exists and bcrypt verifies the correct password, the user receives claims for that account. If the account does not exist or the password is incorrect, the result is “401 Unauthorized.” If the password hash cannot be read, the result is “500 unreadable hash.”
Figure 4. The settled intent map: a token requires the right password for the account, and a right password must succeed. The flow shows the possible outcomes of the password check.
Side-by-side comparison of two authentication policies. The left panel, “Only when,” shows that a token implies the correct password but does not guarantee a token for a correct password. The right panel, “Exactly when,” shows a two-way relationship in which a token is issued if and only if the correct password is provided. The highlighted difference is that denying a token to a user with the correct password is allowed under the first policy but forbidden under the second.
Figure 5. The two interpretations differ in one case: whether a correct password can still be denied a token.

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.

Comparison of two approaches to verifying a login handler. Option A, recommended, keeps the login handler trusted and verifies only the login decision logic, while database lookups and token signing remain tested but trusted components. Option B gives the login handler its own formal specification, proving the orchestration logic but requiring additional trusted wrappers and assumed contracts around database lookups, clocks, and JWT signing.
Figure 6. Extending the proof to more of login also requires trusted wrappers. The plan makes that tradeoff visible before approval.

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_email and Admin::find_by_username: each successful lookup returns the matching row in its own table, or no row.
  • check_password, a wrapper around bcrypt::verify: it errors only when bcrypt can’t read the stored hash, and Ok(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_flow unchanged.

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.

Diagram showing the proof boundary for a formally verified login system. Functionality outside the proof is either not promised or trusted and validated through human review and testing, including SQLite lookups, bcrypt, the system clock, JWT signing, database error handling, and request parsing. At the center, the formally verified portion consists of the login_flow and its components login_core, lookup_target, decide_login, and issue_token, which are proven by Verus for every input.
Figure 7. Where the login proof stops. Verus proves the core for every input. People accept the trusted ring and tests check it. The plan lists what nobody is promising.

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.

Proof map showing how a verified login system is divided between formally proved code and trusted, tested components. Five core functions, including login_flow, login_core, lookup_target, decide_login, and issue_token, are formally verified with Verus. Supporting functions for database queries, password verification, token signing, clock access, and error handling are treated as trusted contracts that are reviewed and tested.
Figure 8. What gets proved and what gets trusted in login. Green functions are proved by Verus for every input. Amber pieces are trusted, accepted by the developer, and checked by the planned tests in the plan’s §4.1.
Proof map showing how a verified login system is divided between formally proved code and trusted, tested components. Five core functions, including login_flow, login_core, lookup_target, decide_login, and issue_token, are formally verified with Verus. Supporting functions for database queries, password verification, token signing, clock access, and error handling are treated as trusted contracts that are reviewed and tested.
Figure 9. A trust card for check_password. Verus takes these two clauses on faith, so a person accepts them and two tests check them.
Screenshot of a test plan for verifying password validation behavior. The section, “check_password_answers_with_bcrypts_verdict,” describes unit tests confirming that password checks return true for the correct password and false for incorrect or empty passwords. Example test cases use bcrypt hashes for customer and administrator accounts.
Figure 10. A planned test for the trusted 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.

Annotated code snippet explaining a formal verification clause for login tokens. The clause states that if a login returns a token, then the request names a valid account, the password matches the stored hash, the token contains valid claims, and the token’s subject and role match the authenticated account. Numbered callouts explain each part of the expression.
Figure 11. The ensures clause on login_flow for “You only get a token with the right password.” The same account a appears on every line, which ties the password check to the token.

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,
/// },
/// }
/// }

Traceability diagram showing how formal verification promises are derived from requirements. Statements made by developers and decisions recorded in design cards are mapped to eight specific guarantees in the login_flow specification, covering token issuance, account roles, invalid credentials, missing accounts, malformed requests, and error handling.
Figure 12. The two-sentence request and the Both ways decision ended up as eight ensures clauses on login_flow. Four of them keep today’s refusals, so the storefront and the existing API tests keep working.

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 in login_flow depends on that assumption.
Flowchart showing the end-to-end login process. A login request selects an account table based on an email or username, looks up the account, verifies the password, and issues a signed token when authentication succeeds. Error paths return appropriate HTTP responses: 400 for missing credentials, 401 for invalid credentials or missing accounts, and 500 for lookup or password-hash failures.
Figure 13. Every outcome in the planned login flow.
The flow’s outcomes are covered together: a token appears only after authentication succeeds; missing credentials, an unknown account, a wrong password, a failed lookup, or an unreadable hash lead to refusals or errors. That’s a meaningful guarantee about the program’s logic, but its strength still rests on the contracts at the edges. There’s another limit specific to async code. Verus checks an async function’s preconditions when the call creates a future, and its postconditions only if awaiting that future returns a value. The contract doesn’t promise the future will finish. A database query that hangs violates no postcondition.
Diagram comparing how formal verification applies to synchronous and asynchronous functions. For both types, preconditions are checked when the function is called and postconditions are guaranteed when a result is returned. In an asynchronous login flow, the function may pause while awaiting a database lookup, and the specification makes no guarantee about whether or how quickly the operation completes.
Figure 14. Preconditions apply at the call; postconditions apply when a result returns, including for async functions.

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.
Annotated map of the verified/src/login.rs file showing the structure of a formally verified login implementation. The diagram categorizes sections as specification-only definitions, trusted external contracts, data types, and five functions formally proved with Verus: login_flow, login_core, issue_token, lookup_target, and decide_login.
Figure 15. The file moves from headers and types through specification-only definitions and trusted contracts to five functions proved with Verus. Gray marks headers and types, purple the contract-only math, amber the trusted code, and green the proved code.

From an approved spec to a checked build

Once the developer approves the specification, the build plan turns it into seven tasks: get login.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.
Screenshot of a PDD Kit build plan for a login-token issuance specification. The build workflow contains seven tasks, with the first task focused on making verified/src/login.rs successfully build under Verus while preserving contract meanings. Subsequent tasks cover proving login-related functions, testing trusted wrappers, running end-to-end login tests, and validating token-signing behavior.
Figure 16. The plan breaks the approved spec into seven tasks. The first makes 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.
Each task pairs implementation and proof work with tests for anything inside the trusted boundary. An LLM verifier checks the plan, specification, and results for requirements that lack either proof or a passing check. Gaps go back to the coding agent; contradictions in the spec return to the developer. That review matters because a proof can pass while saying little. A model may choose weak invariants that verify but rule out almost nothing, a failure mode the team calls “vibe verification.” PDD Kit probes for it by making a scratch copy of the code and introducing one bug for each postcondition—for example, refusing every login or choosing the username search before the email search. Verus must reject each modified version on the clause meant to catch that bug. If a mutant survives, the clause hasn’t constrained the code enough. The loop also stops when a required async construct can’t be expressed in the pinned Verus version. It asks the team what to do instead of silently changing the implementation or relaxing the contract.

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.

Where this approach fits

PDD Kit is a research prototype, and it currently verifies Rust because Verus works on Rust. Existing Rust code needs no language migration; other projects can port selected code to Rust and check it against the same spec, or call verified Rust through bindings. Proofs still take effort, especially the proof work itself. A clear specification helps keep that effort manageable, which is why the process puts so much weight on getting intent right first. The Pet Store login demonstrates the method on one part of one application. Its guarantees are only as strong as the trusted boundary, especially bcrypt’s password check and the two lookups that determine which account a token names. Tests exercise those pieces, but don’t prove their contracts. The team expects the trusted portion to shrink over time and wants to learn how far the method can scale. The change is in what teams review. They still need to define the behavior carefully, but they can spend less of their review effort tracing generated code line by line and more on whether the stated requirements capture what they intend. A proof can then keep the implementation tied to that decision.
Source: Alex Lavaee, Matthai Philipose · www.microsoft.com

Same vesselRelated cargo