sacco-parity-verification

Parity Verification Engine

Ensures a new implementation is behaviorally equivalent to a reference implementation through contract tests with tracked RED-to-GREEN progress.

When to Use

• Rewriting a system (e.g., TypeScript to Rust, monolith to microservices)
• Migrating platforms (e.g., Salesforce org to org)
• Ensuring API backward compatibility after major refactors
• Verifying that a new version behaves identically to the old one

Workflow

1. Reference Analysis

Read the reference implementation and extract behavioral contracts:

# Behavioral Contracts: <system>

| ID | Category | Behavior | Source (ref) | Test Status |
|----|----------|----------|-------------|-------------|
| BC-001 | Auth | Login with valid credentials returns token | auth.ts:45 | RED |
| BC-002 | Auth | Login with invalid credentials returns 401 | auth.ts:52 | RED |
| BC-003 | CRUD | Create entity returns entity with ID | commands.ts:120 | RED |

Sources of contracts:

• Existing test suites (map each test to a contract)
• API endpoint behavior (request -> response mapping)
• Event flows (command -> events emitted)
• Side effects (what changes in DB/filesystem/external systems)
• Edge cases (nulls, empty inputs, boundary values, error conditions)

2. Contract Test Generation

For each contract, write a test against the NEW implementation:

Test file: tests/parity/auth_test.rs (or .py, .ts, etc.)
Test name: test_bc_001_login_valid_credentials_returns_token

Rules:

• Tests MUST fail initially (RED). If they pass immediately, the test is likely wrong.
• Tests MUST NOT depend on implementation details of the NEW system.
• Tests MUST test the same external behavior as the reference.
• Each test maps to exactly one contract ID.

3. Progress Tracking

Maintain docs/parity-status.json:

{
  "reference": "src/routes/commands.ts",
  "target": "crates/new-service/src/routes/",
  "total_contracts": 120,
  "passing": 25,
  "failing": 95,
  "categories": {
    "auth": { "total": 12, "passing": 8, "failing": 4 },
    "crud": { "total": 50, "passing": 15, "failing": 35 },
    "events": { "total": 30, "passing": 5, "failing": 25 }
  },
  "last_updated": "2025-01-20T12:00:00Z"
}

Update after every test run.

4. Implementation Rounds

Work through failing contracts in priority order:

1. Core CRUD operations first
2. Auth/permissions second
3. Edge cases and error handling third
4. Performance parity last

For each round:

• Pick a category or group of related contracts
• Implement until those contracts pass (TDD GREEN)
• Run ALL contracts (not just the new ones) to check for regressions
• Update parity-status.json
• Commit: parity(<category>): <N> contracts now passing [<passing>/<total>]

5. Parity Report

When all contracts pass (or at any checkpoint), produce:

# Parity Report: <system>

## Status: 120/120 passing (100%)

## Category Breakdown
| Category | Passing | Total | Notes |
|----------|---------|-------|-------|
| Auth | 12/12 | 100% | Full parity |
| CRUD | 50/50 | 100% | Full parity |

## Behavioral Differences (Intentional)
| Contract | Reference Behavior | New Behavior | Reason |
|----------|-------------------|-------------|--------|
| BC-089 | Returns XML | Returns JSON | Modernization |

## Known Gaps
| Contract | Status | Plan |
|----------|--------|------|
| BC-120 | SKIP | Deprecated feature, not porting |

Rules

• NEVER change a contract test to make it pass. Change the implementation.
• If a behavioral difference is intentional, document it explicitly.
• Skipped contracts must have documented justification.
• Run the FULL contract suite after every implementation change, not just affected tests.
• Parity means behavior, not implementation. Different code is fine; different behavior is a bug.

Integration

• With sacco-phased-execution: Parity rounds map to phases
• With sacco-codebase-audit: Audit the new implementation after parity is achieved
• With TDD: Contract tests ARE the TDD spec — implementation follows