Skip to content
Merged
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
28 changes: 28 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,32 @@ jobs:
assert result['data']['current'] and result['data']['receipt']['success']
assert result['data']['receipt']['approval']['reviewer'] == 'codex-example-review'
PYTHON
- name: Install the browser test runner outside the source snapshot
run: |
npm install --no-audit --no-fund --prefix "$RUNNER_TEMP/pdd-playwright" @playwright/test@1.65.1
runner="$RUNNER_TEMP/pdd-playwright/node_modules/@playwright/test/cli.js"
node "$runner" install --with-deps chromium
echo "PDD_PLAYWRIGHT_CLI=$runner" >> "$GITHUB_ENV"
- name: Verify the wallet browser flow and HTML evidence
run: |
bin/pdd --plan httpwallet-browser init --from examples/httpwallet/browser/plan.json
bin/pdd --plan httpwallet-browser import-approval --from .pdd/reviews/httpwallet-browser.json
bin/pdd --plan httpwallet-browser prove --json > .pdd/browser-prove-result.json
bin/pdd --plan httpwallet-browser status --json > .pdd/browser-status-result.json
bin/pdd --plan httpwallet-browser report --out .pdd/state/httpwallet-browser/report.html
python3 - <<'PYCODE'
import json
from pathlib import Path
status = json.loads(Path('.pdd/browser-status-result.json').read_text())
assert status['ok'] and status['data']['current']
receipt = status['data']['receipt']
assert receipt['success']
assert any(v['id'] == 'overdraft-screen' and v['status'] == 'evidenced' for v in receipt['requirements'])
browser = next(e for e in receipt['evidence'] if e['check'] == 'wallet-browser')
assert browser['kind'] == 'empirical' and browser['artifacts'][0]['file'] == 'wallet-browser.playwright.json'
report = Path('.pdd/state/httpwallet-browser/report.html').read_text()
assert 'playwright · empirical' in report and 'wallet-browser.playwright.json' in report and 'killed' in report
PYCODE
- name: Upload proof receipts
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
Expand All @@ -83,6 +109,8 @@ jobs:
path: |
.pdd/receipts/
.pdd/state/httpwallet/receipts/
.pdd/state/httpwallet-browser/receipts/
.pdd/state/httpwallet-browser/report.html
.pdd/*-result.json
if-no-files-found: warn
include-hidden-files: true
Expand Down
149 changes: 149 additions & 0 deletions .pdd/reviews/httpwallet-browser.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
{
"schema": 1,
"digest": "de201c3d481e039c7c435f4ce41734a4e25039a6c105e3fdd0b01abca4ebe699",
"reviewer": "codex-example-review",
"accepted_trust": [
"wallet-runtime",
"wallet-sessions"
],
"approved_at": "2026-11-18T06:14:12.837703671Z",
"plan_id": "httpwallet-browser",
"review": {
"schema": 1,
"plan_id": "httpwallet-browser",
"plan": {
"scenarios": [
{
"id": "browser-overdraft",
"check": "wallet-browser",
"test": "wallet.spec.cjs :: rejects an overdraft without debiting the wallet",
"given": "A demo account starts with a balance of 100",
"when": "The user attempts to withdraw 101 then withdraws 100",
"then": "The browser shows a denial followed by a successful withdrawal with zero remaining",
"requirements": [
"overdraft-screen"
],
"purpose": "integration"
}
],
"schema": 1,
"name": "HTTP wallet with browser evidence",
"intent": "The HTTP withdrawal endpoint must use the verified production decision, allowing a withdrawal exactly for an authenticated, unlocked account with a positive amount within its balance. Exercise request decoding, sessions and atomic state updates empirically. Show a refusal in the browser for an overdraw and leave the wallet unchanged.",
"non_goals": [
"The static demo tokens are not production authentication; no TLS, identity proof, persistence, payment settlement or distributed consistency is provided.",
"Gobra proves the pure decision only; HTTP decoding, the session mapping, synchronization and state updates have empirical evidence, not formal proof.",
"Availability, fairness, transport failure recovery and exactly-once request semantics are outside scope."
],
"requirements": [
{
"id": "withdrawal-policy",
"text": "Accept exactly authenticated, unlocked withdrawals with positive amount no greater than balance.",
"kind": "formal",
"check": "withdrawal-proof",
"file": "examples/httpwallet/policy/policy.go",
"function": "CanWithdraw",
"ensures": "allowed == (authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance)"
},
{
"id": "http-boundary",
"text": "HTTP method, path, session and withdrawal boundaries return expected status and balance, without changing funds on rejection.",
"kind": "empirical",
"check": "http-tests"
},
{
"id": "http-decoding",
"text": "Malformed, oversized, ambiguous and unknown request inputs are rejected without changing funds.",
"kind": "empirical",
"check": "http-tests"
},
{
"id": "atomic-withdrawals",
"text": "Concurrent requests through a real local HTTP server spend the initial balance exactly once without overdraft.",
"kind": "empirical",
"check": "http-tests"
},
{
"id": "overdraft-screen",
"text": "A browser shows withdrawal denied for an overdraft and the full starting balance remains available.",
"kind": "empirical",
"check": "wallet-browser"
}
],
"checks": [
{
"id": "withdrawal-proof",
"kind": "gobra",
"files": [
"examples/httpwallet/policy/policy.go"
]
},
{
"id": "http-tests",
"kind": "go-test",
"package": "./examples/httpwallet/app",
"tests": [
"TestWithdrawalHTTP",
"TestMalformedHTTP",
"TestConcurrentHTTPWithdrawals"
]
},
{
"id": "wallet-browser",
"kind": "playwright",
"tests": [
"wallet.spec.cjs :: rejects an overdraft without debiting the wallet"
],
"config": "examples/httpwallet/browser/playwright.config.cjs",
"project": "chromium"
}
],
"trusted_boundary": [
{
"id": "wallet-sessions",
"assumption": "The configured session mapping identifies the correct account and lock state; demo tokens are public test credentials. Tests exercise known, unknown, locked and ambiguous tokens but cannot establish a real identity provider's truthfulness.",
"check": "http-tests"
},
{
"id": "wallet-runtime",
"assumption": "Go integer/JSON/HTTP implementations and mutex semantics are trusted. Race and TCP concurrency tests exercise parsing and an atomic in-memory update; they do not prove the runtime or provide durable financial guarantees.",
"check": "http-tests"
}
],
"mutations": [
{
"id": "ignore-session-lock",
"requirement": "withdrawal-policy",
"check": "withdrawal-proof",
"file": "examples/httpwallet/policy/policy.go",
"find": "return authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance",
"replace": "return authenticated \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance"
},
{
"id": "allow-zero-withdrawal",
"requirement": "withdrawal-policy",
"check": "withdrawal-proof",
"file": "examples/httpwallet/policy/policy.go",
"find": "return authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance",
"replace": "return authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e= 0 \u0026\u0026 amount \u003c= balance"
},
{
"id": "allow-overdraft",
"requirement": "withdrawal-policy",
"check": "withdrawal-proof",
"file": "examples/httpwallet/policy/policy.go",
"find": "return authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance",
"replace": "return authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0"
}
]
},
"sources": [
{
"file": "examples/httpwallet/policy/policy.go",
"annotations": [
"ensures allowed == (authenticated \u0026\u0026 !locked \u0026\u0026 amount \u003e 0 \u0026\u0026 amount \u003c= balance)",
"declarations:package policy\n\nfunc CanWithdraw(authenticated, locked bool, amount, balance int) (allowed bool) {\n}\n"
]
}
]
}
}
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ login-decision: proved (formal)
login-boundary: evidenced (empirical)
```

Open the `receipt.md` path printed by `pdd prove` to see the checks, rejected mutations, trusted assumptions, and proof limits. `pdd status` checks that the latest receipt still matches the current source and approval. For a browser view of the plan and evidence, run `pdd report --out .pdd/results/login.html` and open that file.
Open the `receipt.md` path printed by `pdd prove` to see the checks, rejected mutations, trusted assumptions, and proof limits. `pdd status` checks that the latest receipt still matches the current source and approval. For the requirements, test results, rejected mutations, and links to logs on one page, run `pdd report --out .pdd/results/login.html` and open the HTML file.

## Use it in your project

Expand All @@ -64,14 +64,14 @@ If you already work with a coding agent, `pdd draft` can turn a request into an

| Example | What to look at |
| --- | --- |
| [HTTP wallet](examples/httpwallet/README.md) | A real HTTP handler calls a proved withdrawal rule. Go tests exercise session handling, invalid requests, and concurrent withdrawals. |
| [HTTP wallet](examples/httpwallet/README.md) | A real HTTP handler calls a proved withdrawal rule. Go tests exercise the HTTP boundary and concurrent withdrawals. The optional browser check submits an overdraft and confirms the balance remains available. |
| [Multi-package authorization](examples/authorization/plan.json) | A handler calls local policy methods. PDD checks the dependency package before the caller. |
| [Slice validation](examples/validation/README.md) | A production loop proves a property over every element using permissions, a quantified contract, and loop invariants. |

## What you can rely on

- **Formal proofs cover stated contracts.** Gobra checks supported Go functions and methods, including supported calls across packages in one module. External and standard-library imports in proof packages remain outside the supported scope. [Supported proof inputs](docs/plan-format.md)
- **Go tests provide evidence for the cases they run.** The receipt labels them separately from proofs. Each planned negative mutation must fail on the intended postcondition. A missing test, tool failure, or inconclusive mutation fails verification. [Design](docs/design.md)
- **Go and browser tests provide evidence for the cases they run.** The receipt labels them separately from proofs. Each planned negative mutation must fail on the intended postcondition. A missing test, tool failure, or inconclusive mutation fails verification. [Design](docs/design.md)
- **Receipts tie the result to the reviewed change.** Machine-readable JSON and Markdown include the plan and source digests, commands, outcomes, trust assumptions, and links or references to saved logs. `status` rejects stale evidence. Use Ed25519 approvals with a trusted policy when CI needs to verify reviewer authority. [JSON protocol](docs/cli-json.md) · [Signed reviews](docs/signed-reviews.md)

`pdd-kit-go` is an independent implementation of ideas from the Proof-Driven Development Kit research prototype. Its Go verifier is Gobra. [Original PDD Kit](https://githubnext.com/projects/pdd-kit/) · [Feature comparison and limits](docs/reference-comparison.md)
Expand Down
63 changes: 63 additions & 0 deletions docs/browser-checks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Browser checks with Playwright

A `playwright` check runs an existing Playwright Test project in the same kind of
isolated source copy as a Go test. PDD verifies the required test identities in
the final JSON report and saves it with the receipt. HTML reports link to the
execution log, the Playwright JSON, and any saved failure screenshots and traces.

## Run the wallet example

Use a Go toolchain, the pinned Gobra image, and Node.js 20 or newer for this
example. Install Playwright and Chromium once on the machine running the check.
Run these commands from the repository root with a `pdd` binary built from this
checkout.

```sh
browser_tools=$(mktemp -d)
npm install --prefix "$browser_tools" @playwright/test@1.65.1
export PDD_PLAYWRIGHT_CLI="$browser_tools/node_modules/@playwright/test/cli.js"
node "$PDD_PLAYWRIGHT_CLI" install chromium

pdd --plan httpwallet-browser init --from examples/httpwallet/browser/plan.json
pdd --plan httpwallet-browser plan
pdd --plan httpwallet-browser import-approval --from .pdd/reviews/httpwallet-browser.json
pdd --plan httpwallet-browser prove
pdd --plan httpwallet-browser status
pdd --plan httpwallet-browser report --out .pdd/state/httpwallet-browser/report.html
```

Open the generated HTML alongside its `receipts/` directory so relative links
work. The saved example approval is a demonstration assertion. Review and approve
your own project's requirements and trust assumptions separately. On Linux,
`node "$PDD_PLAYWRIGHT_CLI" install --with-deps chromium` can also install the
browser's system dependencies.

## Adopt an existing suite

- Point `PDD_PLAYWRIGHT_CLI` to an absolute `node_modules/@playwright/test/cli.js`
path. `node` must be on `PATH`. Provision the runner and any CommonJS test
dependencies together. PDD sets `NODE_PATH` to that `node_modules` directory.
The check performs no dependency installation.
- Add a check of kind `playwright` with `config`, `project`, and `tests` in the
[plan format](plan-format.md). Use a standalone Playwright project and a
repository-relative configuration. PDD runs that project without project
dependencies and verifies every required test against the completed result.
Use a config that starts its own local app and keeps output out of the source
snapshot. The wallet config sets `reuseExistingServer: false`.
- Keep project code, config, and tests in the captured snapshot. You can put the
preinstalled dependencies outside the repository, or explicitly exclude
`node_modules` via the reviewed `inputs.exclude` policy. Browser plans allow
only `node_modules` exclusions in addition to PDD's default reserved paths.
Use CommonJS-compatible dependency resolution for externally provisioned
packages. Fully native ESM imports do not use `NODE_PATH`.
- Set `use.screenshot` to `only-on-failure` if you want failure images. PDD
requests tracing on failure and retains bounded PNG/trace artifacts from
Playwright's output directory. Open a saved trace with
`node "$PDD_PLAYWRIGHT_CLI" show-trace PATH_TO_TRACE.zip`. Browser artifacts can
contain private page content or network data. Share them with the same care as
test logs.

The runtime and browser are part of the empirical test environment. Playwright's
configuration and tests run with the invoking user's permissions, as Go tests do.
Browser checks provide evidence for the cases that actually ran. Gobra continues
to prove the Go contracts separately.
5 changes: 5 additions & 0 deletions docs/cli-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,3 +80,8 @@ and conservative pruning candidates. `build` returns stage, success, decision-ne
state, applied edits, iterations and artifact paths; success=false exits 1.
`report` returns its written HTML path. `pr` returns the evidence body/path and a URL
only after explicit successful `--create`. All use the same schema-1 envelope.

Playwright evidence can include an `artifacts` array on a receipt check. Each
entry has a receipt-relative `file` and `sha256`. The JSON test report is required
for a successful browser check. Optional PNG and trace ZIP files preserve failure
context. `status` revalidates referenced files and the required test results.
2 changes: 1 addition & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The selected image is Gobra `v26.09`, resolved and pinned to `sha256:5e96431b06c
- `packages.go` resolves complete same-module proof packages, receiver-qualified symbols and the dependency DAG. It rejects ambiguous import resolution and unverified callee packages.
- `inputs.go` validates reviewed asset exclusions and the protected Go input closure; `snapshot.go` captures bounded inputs, modes and directories and creates separate check/mutation workspaces.
- `approval_transfer.go` exports/imports complete matching reviews without minting CI approvals.
- `runner.go` invokes only Gobra and named Go tests, distinguishes operational failures and validates actual results.
- `runner.go` invokes Gobra and named Go tests. `browser.go` runs a reviewed Playwright project and validates first-attempt results for the named tests.
- `prove.go` joins the evidence, rejects gaps and staleness, and writes receipts.

Formal evidence covers exactly the clauses checked by the Gobra invocation. The production function is both compiled by Go and passed directly to Gobra. The baseline check succeeds first; each mutant must then fail on the target clause. No successful test can replace a failed formal obligation.
Expand Down
Loading
Loading