Verification Contracts

August 9, 2026 ยท View on GitHub

This directory defines the portable verification contract for Rust repositories that adopt RIPR-backed badges and PR evidence.

The contract keeps public repo state and pull-request evidence separate:

Badges summarize repo state.
PR evidence routes work.
Neither impersonates the other.

Badges are the public front panel. They are repo-scoped, generated, and small enough to be true. PR evidence is the instrument cluster. It is diff-scoped, artifact-backed, and detailed enough to route review, agent work, and expensive verification.

Contract Map

ContractOwns
Badge contractPublic Shields endpoint JSON, repo-scope boundary, and badge claim limits.
PR evidence contractDiff-scoped evidence summary, review guidance fields, and routing signal.
Artifact layoutStandard paths for committed badge endpoints and generated CI artifacts.
Annotation policyNon-blocking annotation rules and the inline-comment opt-in boundary.

Machine-readable schemas live under schemas/:

SchemaValidates
schemas/badges/shields-endpoint.schema.jsonPublic committed badge endpoint JSON.
schemas/ripr/pr-evidence.schema.jsonCanonical PR evidence summary packet.
schemas/ripr/review-comments.schema.jsonripr review-comments guidance output.
schemas/ripr/gate-decision.schema.jsonripr gate evaluate decision output and its structured repair route.
schemas/ripr/check.schema.jsonripr check --json primary findings and typed analysis-outcome output.
schemas/ripr/repair-assurance.schema.jsonDesign-only RepairAssuranceV1 envelope and the producer-owned command-spec and execution-result shapes.
schemas/ripr/rust-repair-trust-corpus.schema.jsonAuthorized Rust repair attempt corpus of record.

The schema set and valid fixture packets are checked by:

cargo xtask check-verification-contracts
cargo xtask check-verification-contracts --check

Schema producer audit records, for every published schema, which producer emits the bytes it describes, which canonical subject and negative mutation prove that, and which schemas carry an explicit exemption.

Adoption Boundary

An adopted repository should expose the same command and path shape:

cargo xtask badges
cargo xtask badges --check
cargo xtask ripr-pr
cargo xtask ripr-pr --check
cargo xtask ripr-review-comments
cargo xtask ripr-review-comments --check
cargo xtask ripr-pr-summary
cargo xtask ripr-pr-summary --check
cargo xtask ripr-annotations
cargo xtask ripr-annotations --check
cargo xtask impacted-evidence
cargo xtask impacted-evidence --check

The command set can be implemented in local xtask code, copied from a template, or wrapped around public ripr commands. The contract is the stable part: command names, output paths, schema shapes, and advisory defaults should not drift across repos.

Non-Goals

This contract does not:

  • make RIPR findings blocking by default;
  • publish inline PR comments by default;
  • turn a badge into coverage, mutation proof, correctness proof, or release proof;
  • require full mutation testing on every pull request;
  • define a fleet dashboard;
  • require a public helper crate.

Relationship To Existing Docs

docs/VERIFICATION.md is the short repo-local guide for readers. These files are the portable implementation contract. Existing RIPR workflow docs still own their detailed surfaces: