From 0bc6b1529112866ca7ef2cc9f610a075f4f961ad Mon Sep 17 00:00:00 2001
From: Research Assistant <research@example.com>
Date: Fri, 5 Jun 2026 11:08:13 +0800
Subject: [PATCH] test: lock OCR phase4 version state contract

---
 tests/test_ocr.py          | 34 ++++++++++++++++++++++++++++++++++
 tests/test_ocr_versions.py | 22 ++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 tests/test_ocr_versions.py

diff --git a/tests/test_ocr.py b/tests/test_ocr.py
index a4b63bcc..bf00c5f7 100644
--- a/tests/test_ocr.py
+++ b/tests/test_ocr.py
@@ -509,3 +509,37 @@ def test_postprocess_writes_ocr_health(tmp_path: Path) -> None:
 
     # Phase 3: health/ocr_health.json does not exist yet -- this test will fail
     assert (ocr_dir / "health" / "ocr_health.json").exists()
+
+
+def test_version_state_classifiable_from_meta_json(tmp_path: Path) -> None:
+    import json
+
+    from paperforge.worker.ocr import postprocess_ocr_result
+
+    vault = tmp_path / "vault"
+    vault.mkdir()
+    (vault / "paperforge.json").write_text(
+        json.dumps({"vault_config": {"system_dir": "System", "resources_dir": "Resources"}}),
+        encoding="utf-8",
+    )
+    ocr_root = vault / "System" / "PaperForge" / "ocr"
+    ocr_root.mkdir(parents=True)
+    ocr_dir = ocr_root / "VST001"
+    ocr_dir.mkdir()
+    (ocr_dir / "meta.json").write_text(
+        '{"zotero_key":"VST001","ocr_status":"done","ocr_model":"PaddleOCR"}',
+        encoding="utf-8",
+    )
+
+    _, _, _, _ = postprocess_ocr_result(vault, "VST001", [])
+
+    meta = json.loads((ocr_dir / "meta.json").read_text(encoding="utf-8"))
+    from paperforge.worker.ocr_versions import classify_version_state
+
+    state = classify_version_state(
+        meta=meta,
+        expected_raw={"ocr_model": meta["raw_version"]["ocr_model"], "ocr_provider": "PaddleOCR"},
+        expected_derived={"renderer_version": "2.0.0"},
+    )
+    assert "raw_upgradable" in state
+    assert "derived_stale" in state
diff --git a/tests/test_ocr_versions.py b/tests/test_ocr_versions.py
new file mode 100644
index 00000000..b28b5af1
--- /dev/null
+++ b/tests/test_ocr_versions.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+
+def test_version_state_distinguishes_raw_vs_derived_drift() -> None:
+    from paperforge.worker.ocr_versions import classify_version_state
+
+    state = classify_version_state(
+        meta={
+            "raw_version": {"ocr_model": "PaddleOCR-VL-1.5", "pdf_fingerprint": "sha256:a"},
+            "derived_version": {"renderer_version": "1.0.0-compat"},
+        },
+        expected_raw={
+            "ocr_model": "PaddleOCR-VL-1.6",
+            "pdf_fingerprint": "sha256:a",
+        },
+        expected_derived={
+            "renderer_version": "2.0.0",
+        },
+    )
+
+    assert state["raw_upgradable"] is True
+    assert state["derived_stale"] is True