# ITHZ Invariant Diff

ITHZ Invariant Diff is a local-first diff product for AI-assisted projects and
ITHZ memory archives.

It answers a narrower question than a normal visual diff:

```text
Did the information state change, or did only the representation change?
```

The first product surface is a CLI inside ITHZ-MCP:

```powershell
python -m ithz_mcp ithz-diff before after --mode project --json report.json --report report.html
python -m ithz_mcp ithz-diff old.project.ithz new.project.ithz --mode ithz --json report.json
```

## Product Position

This is not a Diffchecker clone and not a general semantic oracle.

- Diffchecker answers: what text or visual bytes differ?
- Beyond Compare answers: what should be merged or synchronized?
- SemanticDiff answers: what changed in source code structure?
- ITHZ Invariant Diff answers: did the canonical information state or audit
  boundary change?

The intended first segment is AI-assisted project review:

- an agent reformatted, moved or rewrote many files;
- a project memory archive changed after a task;
- a reviewer needs to prioritize material, risk and claim-boundary changes;
- a replication or ledger package needs an auditable delta.

## Relationship To Native ITHZ

`native_ithz` is the physical archive engine. It already separates:

- archive bytes;
- `semantic_plan_hash`;
- `project_semantic_hash`;
- `archive_semantic_hash`;
- safe verification;
- explicit experimental writer modes.

Invariant Diff does not change archive format, CFC planning, family assignment,
payload methods or P10 extraction safety. In `.ithz` mode it uses the existing
native safe verify and archive-layer extraction path through ITHZ-MCP.

The archive verdict is based primarily on `archive_semantic_hash`, with
`project_semantic_hash` and ledger/event deltas reported separately.

## Relationship To ITHZ-MCP

`ithz_mcp` provides the memory projections that make this product unique:

- append-only events;
- decisions, gates, risks and must-not-break rules;
- prompt summary memory;
- workflow profiles;
- project ledger claims and blocked claims;
- replication-pack and reviewer-note records.

Invariant Diff treats claim, blocked-claim, replication-pack and reviewer-note
event changes as claim-boundary changes. Risk, gate and must-not-break events
are risk-relevant changes.

## MVP Inputs

Current MVP supports:

- folder vs folder;
- `.ithz` archive vs `.ithz` archive.

Folder mode excludes `.ithz` archives by default because project-source diffs
and project-memory diffs are different review surfaces. Use `--mode ithz` for
memory archives.

## MVP Outputs

The CLI emits:

- terminal summary;
- optional JSON report;
- optional HTML report;
- optional canonical hashes JSON.

Example:

```powershell
python -m ithz_mcp ithz-diff project_before project_after `
  --mode project `
  --json out\diff_report.json `
  --report out\diff_report.html `
  --canonical-hashes out\canonical_hashes.json
```

Report schema:

```json
{
  "schema": "ithz_invariant_diff_report_v1",
  "verdict": "MATERIAL_CHANGE",
  "canonical_equal": false,
  "counts": {
    "material": 7,
    "representation_only": 143,
    "risk_relevant_change": 3,
    "claim_boundary_change": 1
  },
  "review_priority": [
    "config/security.yml",
    "docs/D_BRANCH_STATUS.md"
  ]
}
```

## Verdicts

Verdicts are intentionally conservative:

- `EQUIVALENT`;
- `REPRESENTATION_ONLY_CHANGED`;
- `STRUCTURAL_ONLY_CHANGED`;
- `MATERIAL_CHANGE`;
- `RISK_RELEVANT_CHANGE`;
- `CLAIM_BOUNDARY_CHANGE`;
- `UNKNOWN_NEEDS_REVIEW`.

Unknown binary changes are never treated as equivalent.

## Normalization Rules

Folder mode:

- ignores file traversal order;
- normalizes line endings and trailing whitespace for text;
- canonicalizes JSON key order;
- ignores timestamp-like JSON keys through an explicit JSON canonicalizer;
- detects moved or renamed files by canonical content hash;
- treats Markdown section moves as structural when section units are unchanged;
- marks binary changes as unknown.

Archive mode:

- safe-verifies the archive through the existing native path;
- compares `archive_semantic_hash` as canonical archive identity;
- compares non-local prompt summaries by semantic prompt hash;
- compares append-only memory events by semantic event hash;
- classifies ledger and reviewer changes as claim-boundary changes.

## Claims That Must Not Be Made

Do not claim:

- the tool understands all document meaning;
- the tool proves two arbitrary projects are semantically identical;
- the tool replaces Git, normal review or safe verification;
- ITHZ archives are generally superior to ZIP/tar.gz/7z;
- ITHZ-MCP is a production database or cloud sync product.

Use this wording:

```text
canonical/invariant diff with explicit normalizers
```

Avoid this wording:

```text
AI understands your project perfectly
```

## Next Product Steps

1. Add explicit policy profiles for normalizer defaults.
2. Add native archive pair diff helpers so `.ithz` mode can avoid temp-project
   copying.
3. Add first-class CLI install wrapper `ithz-diff`.
4. Add code-symbol extraction for Python and TypeScript.
5. Add MCP tools:
   `ithz_diff_projects`, `ithz_diff_current_vs_checkpoint`,
   `ithz_diff_claims`, and `ithz_explain_material_changes`.
