# PPT + Invariant Testing Doctrine
This is a copy of the doctrine from the local file `ppt_invariant_guide.md` (Downloads) so it’s versioned alongside the rest of the project documentation.
---
# Unified Guide: PPT + Invariant Testing System for AI-Assisted and Complex Projects
This guide provides a lightweight, enforceable, and extensible framework that combines **Predictive Property-Based Testing (PPT)** with **runtime invariant enforcement**. It's designed for teams or solo devs working in high-churn, AI-assisted, or exploratory projects that still demand test rigor and architectural discipline.
---
## Core Concept
Traditional TDD fails under high-change systems. This system embraces volatility by:
1. **Focusing on Properties**, not implementations.
2. **Embedding Invariants** directly into business logic.
3. **Automating Test Lifecycle** to prevent test bloat.
4. **Tracking Invariant Coverage** to enforce contract-level guarantees.
---
## Layered Test System Overview
| E-Test | Exploration (temporary) | `explore_test()` or free tests |
| P-Test | Property test (generic input, stable behavior) | `property_test()` + invariants |
| C-Test | Contract (permanent, must-pass) | `contract_test()` + tracking |
---
## Invariant System Summary
### Define Invariants in Code
```rust
assert_invariant(payment.amount > 0, "Payment must be positive", Some("checkout flow"));
```
- **Logs the assertion**
- **Crashes on violation**
- **Records presence** for later contract checks
### Track Them in Contract Tests
```rust
contract_test("payment processing", &["Payment must be positive"]);
```
### Reset Between Runs (Optional CI Cleanup)
```rust
clear_invariant_log();
```
---
## How It Guides AI or Human Developers
- **Invariant Failures** give immediate semantic feedback.
- **Property Tests** ensure robustness across inputs.
- **Contract Tests** enforce that critical rules are still checked after refactors or codegen.
- **No test passes unless the real-world expectations are still actively enforced.**
---
## Setup and Tooling (Rust)
### Add Dependency
```toml
# Cargo.toml
[dependencies]
lazy_static = "1.4"
```
### Include System
```rust
mod invariant_ppt;
use invariant_ppt::*;
```
### Suggested File Layout
```
src/
invariant_ppt.rs
logic.rs
tests/
mod.rs
test_properties.rs
test_contracts.rs
```
---
## Expansion Ideas
- **CI contract coverage audit**: fail if key invariants are missing.
- **Property test fuzzing**: integrate with proptest/quickcheck.
- **Cross-language parity**: reuse concept in TS, Python, Go.
- **IDE plugins**: mark critical paths without invariants.
---
## Why Use This
- Forces you to **define real expectations**, not just examples.
- Helps AI systems learn and conform to those expectations.
- Protects your system’s **semantic integrity during rapid iteration**.
- Eliminates “silent failure” drift across modules.
---
## Minimal Startup Checklist
-
---
**Status: Production-ready base. Expandable to full verification model.**