Parity Contract

This document defines the comparison contract and CI gate behavior used by parity workflows.

Scope

• Applies to OOXML parity calibration and PR parity-drift gating.
• Baseline target: Open XML SDK v3.4.1.
• Baseline artifacts:
• data/corpus/sdk_seed/manifest.json
• data/corpus/parity_baseline/v3.4.1/parity_snapshot.json
• data/corpus/parity_baseline/v3.4.1/perf_budget.json
• data/corpus/parity_baseline/v3.4.1/waivers.json

Snapshot Schema

Current snapshots are produced by scripts/corpus/run_parity_snapshot.py and include:

• duration_seconds
• validation_runs
• checks_collected
• checks_total
• checks_matched
• checks_mismatched
• checks_missing_files
• match_rate_percent
• strict
• include_mutation_expectations
• skipped_mutation_expectations
• mismatch_families[] with normalized tuple fields:
• id
• error_type
• part
• path
• description
• family_key (id|error_type|part|path|description)
• count

Expectation Scenarios

Expectations extracted from SDK tests are tagged in the manifest with scenario:

• base: validation of an unmodified corpus file
• mutation: validation after test-time document mutations (add/remove/edit operations)

Extractor normalization for parity fidelity:

• Only package-level OpenXmlValidator.Validate(package) assertions are mapped to file-level expectations.
• Part/element-level validations and max-error harness flows (for example MaxNumberOfErrors tests) are tagged as mutation.

Default parity snapshots run against base expectations only.

• scripts/corpus/run_parity_snapshot.py excludes scenario == "mutation" unless --include-mutation-expectations is passed.
• Excluded counts are reported as skipped_mutation_expectations in the snapshot JSON.

Comparison Contract

scripts/corpus/compare_to_baseline.py compares a current snapshot against baseline and enforces:

• mismatch growth (checks_mismatched delta)
• new mismatch-family count
• match-rate drop
• missing-file checks
• check-count drop (unless explicitly allowed)
• strict-mode drift (if required)

Family drift is keyed by family_key when present (falls back to description for older snapshots).

Default policy is strict no-drift:

• --max-mismatch-growth 0
• --max-new-families 0
• --max-match-rate-drop 0.0
• --max-missing-files 0
• --require-same-strict
• disallow checks_total drop

PR Gate Behavior

Workflow: .github/workflows/parity-gate.yml

• Runs snapshot with current code.
• Compares to baseline via compare_to_baseline.py.
• Enforces runtime budget via check_perf_budget.py.
• Uploads reports and step summary.
• Fails PR on policy violations.

Corpus source for gate:

• Local data/corpus/sdk_seed/files/ if present.
• Otherwise downloads archive from repository variable PARITY_CORPUS_ARCHIVE_URL.

Archive requirement:

• Compressed .tar.zst that extracts a top-level files/ directory.

Performance Guard

Performance budget is defined in data/corpus/parity_baseline/v3.4.1/perf_budget.json.

scripts/corpus/check_perf_budget.py validates:

• max total snapshot duration (max_duration_seconds)
• max duration per evaluated check (max_seconds_per_check)
• max duration per validator run (max_seconds_per_validation)
• minimum evaluated checks (min_checks_total)

Default policy is fail-on-regression against these limits in PR CI.

Waiver Process

Waivers are declared in data/corpus/parity_baseline/v3.4.1/waivers.json.

Required fields per waiver:

• kind: one of
• new_mismatch_family
• mismatch_growth
• match_rate_drop
• missing_files
• check_total_drop
• strict_mode
• owner: accountable owner/team
• reason: short rationale
• expires: ISO date YYYY-MM-DD
• target: required for new_mismatch_family (family description)

Rules:

• Expired waivers are ignored.
• Invalid waiver entries are ignored and surfaced as warnings in compare output.
• Waivers are temporary by design; renew only with explicit rationale.

Example:

{
  "waivers": [
    {
      "kind": "new_mismatch_family",
      "target": "file_not_found",
      "owner": "openxml-audit-maintainers",
      "reason": "Temporary corpus mirror outage",
      "expires": "2026-04-15"
    }
  ]
}

SDK Usage Policy

• SDK validation remains available for calibration and deep investigations.
• Daily development and PR CI must not depend on local SDK installation.