Skip to content

Contributing

Ryan Cole edited this page Nov 15, 2026 · 2 revisions

Contributions are welcome under Apache-2.0. The canonical rules are CONTRIBUTING.md; this page is a summary.

Code written with an AI assistant is welcome (most of this codebase is). Review what you submit.

What a change needs

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
pwsh harness/host/test.ps1            # for hook host changes
pwsh harness/host/test.ps1 -Arch x86  # and its 32-bit build
  • A change to analysis, matching or verification has tests with a negative case (something that must not match or must not be accepted) and keeps wrong matches at zero on the corpus, x64 and x86. Say in the PR whether the corpus scorecards were run.
  • Uncalibrated thresholds are tagged [Guess] in the design doc.
  • No GPL dependencies.
  • No features for unpacking, defeating integrity checks, or evading anti-cheat or anti-tamper.

Layout

crates/
  permanent-beta-model/     shared types
  permanent-beta-analysis/  binary → analysis
  permanent-beta-match/     matching passes → candidates (never decides)
  permanent-beta-verify/    checks and acceptance policy
  permanent-beta-repair/    per-hook repair, patterns, header, host config
  permanent-beta-replay/    replay by emulation (optional `emulator` feature)
  permanent-beta-store/     mapping history and review queue
  permanent-beta-engine/    match → verify → repair
  permanent-beta-cli/       pbeta
  permanent-beta-mcp/       pbeta-mcp
  permanent-beta-ai/        AI proposer
  permanent-beta-corpus/    test tooling: answer keys and scoring
harness/host/               hook host (C++, Detours)
integrations/ghidra/        exporter and review extension
integrations/ida/           IDA plugin
corpus/                     ground-truth corpus

match and verify never depend on each other. Allowed dependencies between crates are listed in CLAUDE.md.

The corpus

Real projects (zlib, Lua, zstd, TinyXML-2, yaml-cpp, JsonCpp) built across versions and flags, for x64 and x86, scored against answer keys. It takes a long time, so it runs only on demand: in Actions (ci → Run workflow, tick "corpus") or locally with pwsh corpus/build-fixtures.ps1 -Score, pwsh corpus/build-projects.ps1 -Score and pwsh corpus/build-hooks.ps1 -Run; add -Arch x86 to each for the 32-bit variants. See corpus/README.md.

Clone this wiki locally