# Proofborne
**The coding agent that proves its work.**
Proofborne is a local-first, vendor-neutral coding harness for power users. Its core
primitive is a **Task Contract** backed by a runtime-generated **Proof Graph**. A model
may claim that work is complete; Proofborne only reports `verified` when every required
criterion has passing evidence or an explicit human waiver.
The product mission is **Completion Integrity**: make every completion claim scoped,
falsifiable, bound to the state it observed, and portable enough to review offline.
Read the versioned [product vision](docs/product-vision.md) and the decision on
[claim scopes and assurance](docs/adr/0003-claim-scopes-assurance-and-evidence-kernel.md).
> Status: early `0.1.0-alpha` development. Public JSONL and proof-bundle schemas are
> versioned; internal Rust APIs are not stable yet.
## What works in the first vertical slice
- one Rust binary on Windows, Linux, and macOS;
- live interactive terminal UI and machine-readable JSONL mode over one session engine;
- hash-chained event records, SQLite WAL persistence, and content-addressed artifacts;
- task contracts, evidence linking, completion gates, and provider-free semantic offline proof verification;
- policy presets and hash-precondition file edits;
- deterministic mock provider plus streaming direct HTTP provider adapters and ordered
fallback that stops after a side effect;
- hierarchical `AGENTS.md`, progressive Agent Skills discovery, and brokered MCP
tools/resources/prompts over stdio or HTTP;
- ACP v1 stdio sessions, prompt updates, cancellation, load/recovery, and close, including
client-provided `mcpServers` over stdio and Streamable HTTP on the current development
branch.
## Quick start
```console
cargo build --release
./target/release/proofborne init
./target/release/proofborne run --profile mock --task "Inspect this repository" --auto-contract --jsonl
./target/release/proofborne session list
./target/release/proofborne proof export <SESSION_ID> --output proof.zip
./target/release/proofborne proof verify proof.zip
```
The mock provider is deliberately deterministic. A runtime-only auto-contract cannot
prove a coding task and therefore ends `blocked` before mutation when no task-specific
verifier can be constructed; it never returns task-scoped `verified` or exit code `0`.
Use a confirmed contract plus runtime verification for a proof-bearing task.
For a complete guarded edit with a failing-then-passing test, use
[`examples/provable-edit`](examples/provable-edit). It demonstrates the actual sequence
`read → hash-precondition patch → runtime test → proof gate` without an API key.
## Current alpha boundary
This repository implements the end-to-end vertical slice and the public proof core.
Same-session crash recovery now pins the event cursor, provider/model, step ceiling,
verification plan, workspace state, side-effect watermark, and authority snapshot. It
continues provider failures and untouched pending calls, but blocks ambiguous in-flight
side effects and partial provider streams instead of replaying them. Remote OAuth/coding-
plan login and release signing remain tracked work. Docker uses a pinned image, an
explicit workspace mount, and no network by default; requested Docker network access
needs an interactive per-run approval. Additional read-only host mounts are deliberately
rejected in v0.1. If Docker is required but unavailable or invalidly configured, the
runtime fails closed; `auto` and `host` are explicitly labeled **policy-enforced, not
sandboxed**.
ACP-provided MCP credentials remain ephemeral: environment and header values are added
to the runtime redactor but are not written to ACP session metadata, events, JSONL, or
proof bundles. The persisted, secret-free tool-authority hash binds recovery to the
declared server descriptors and discovered tool definitions. A changed authority or an
ambiguous in-flight network action blocks recovery; Proofborne does not replay that
call. Client attachments require both `proofborne acp --allow-client-mcp` and an exact
alias (or `*`) in `policy.mcp_allow`. ACP advertises modern HTTP support only when that
operator gate is enabled and explicitly reports legacy SSE as unsupported.
The versioned [conformance corpus](tests/conformance/README.md) captures adversarial
completion, freshness, tampering, recovery, approval, fallback, and redaction
expectations. Its structural validator and deterministic runtime-backed semantic gate
run in CI. The development branch also runs `scripts/validate_acp_mcp.py` against the
real ACP subprocess and Rust MCP fixture to check lifecycle, cancellation, secret
redaction, JSON-RPC-only stdout, and no-replay recovery. These are internal conformance
gates, not an external benchmark or a production-release claim.
Architecture, configuration, proof layout, compatibility, and the exact shipped/next
boundary are documented under [`docs/`](docs/implementation-status.md). The staged
crate and binary publication gates are described in
[`docs/releasing.md`](docs/releasing.md).
## Trust model
Proofborne v0.1 proves that captured evidence is internally consistent and that the
declared completion gate was applied. It does **not** prove mathematical correctness,
capture activity outside its tool boundary, or defend against a compromised host that
can rewrite both the evidence and verifier. See [THREAT_MODEL.md](THREAT_MODEL.md).
Proofborne does not currently claim mathematical correctness, remote attestation,
complete sandboxing, or superiority over another harness. “Best”, “safest”, and
“revolutionary” remain ambitions until reproducible comparisons support a narrower
public statement.
## Project principles
1. Runtime facts outrank model prose.
2. No hidden fallback after side effects.
3. Host policy is never marketed as a sandbox.
4. Secrets never belong in project configuration or proof exports.
5. Compatibility comes from open protocols, not proprietary harness coupling.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)); or
- MIT License ([LICENSE-MIT](LICENSE-MIT))
at your option.