phase: 147_sync_changed_only

All defaults match. Verification complete — everything is green with no defects found.

**Phase 147 final verification pass — report**

- All 3 task files found in `complete/147_sync_changed_only/` → verification pass only; no code changes needed.
- Verified: migration 0025 (`documents.file_hash` nullable String(64), no index) + model field; fast path at top of `_index_file` (streamed 1 MiB sha256 → row lookup → `_unchanged_doc`); stamping on all three branches' create/update + shared helper; pre-phase NULL-hash fallthrough; retriever/`content_hash` untouched.
- **Tests:** `uv run pytest --cov=app --cov-report=term-missing` → 3438 passed, `app/` coverage **99%** (>90% ✓); `uv run pytest tests/e2e/test_sync_changed_only.py -v --no-cov` → 3 passed in isolation ✓; `uv run ruff check . && uv run pyright` → all checks passed, 0 errors ✓; prior-phase `tests/e2e/test_sync_button.py` → 3 passed (no regression) ✓.
- **Completion criteria:** all 7 pass — (1) column + round-trip ✓ (2) unchanged text/image/garbage-PDF/pictorial-PDF cost zero LLM/extraction/vision, `summary.unchanged` counted, rows byte-still ✓ (3) changed file re-indexes + re-stamps; bytes-changed/content-same stamps only ✓ (4) backfill/D1/D4 + log wordings pinned verbatim ✓ (5) `content_hash`/retriever byte-identical ✓ (6) all gates green ✓ (7) no prior-phase behavior change ✓.
- **Documentation:** full review of README.md (1,031 lines) and AGENTS.md against the code: every `.env.example`/code `BOR_*` var documented, all config defaults match `app/config.py`, quick-start/QA commands and referenced test files exist, `file://` URL + troubleshooting claims accurate; the phase's README "Updating the documents" edit is accurate. **Verified consistent — no changes needed.**
- **Notable:** no live-infrastructure changes (dev Postgres container used for the standard test gates only). Working tree left uncommitted per harness protocol.
- **Next pending phase:** `148_pdf_pages_in_sources`.

tests/unit/test_importer.py

@@ -1990,18 +1990,19 @@ def test_fallback_unrenderable_page_gets_the_placeholder(
         _cleanup_source(db, "halfblind")
 
 
-def test_fallback_rerun_lands_unchanged_no_reembed(
+def test_fallback_rerun_unchanged_fast_path_no_reburn(
     db, tmp_path: Path, caplog: pytest.LogCaptureFixture
 ) -> None:
-    """Digest stability (the task's re-burn guard): the digest runs
-    over the constructed fallback content — a re-sync of an unchanged
-    garbage PDF (same pages + the deterministic fake's same replies)
-    re-imports as UNCHANGED: the fallback re-runs (the gate + the
-    render are cheap; the vision calls are re-issued — the documented
-    no-cache cost), but the digest MATCHES, so the row is skipped —
-    no re-chunk, no re-embed, no re-summary, no KB change (the row is
-    not ``updated`` and records no changed path). The doc's content
-    and digest are byte-stable across the re-sync."""
+    """Phase 147 (task 02) — the owner's core complaint, fixed: a
+    re-sync of an unchanged garbage PDF (same raw bytes) takes the
+    FAST PATH at the top of ``_index_file`` (the file hash matches)
+    — the fallback does NOT re-run: the gate never fires
+    (``pdfs_screenshotted`` stays 0 on run 2), no re-extract, no
+    re-render, and the vision calls are NOT re-issued (the previous
+    "vision calls re-issued before the unchanged check can skip them"
+    no-cache cost is gone). The row re-imports as UNCHANGED — no
+    re-chunk, no re-embed, no KB change (not ``updated``, no changed
+    path) — and the doc's content/digest are byte-stable."""
     root = tmp_path / "stable"
     root.mkdir()
     _build_garbage_pdf(root / "stable.pdf")
@@ -2010,19 +2011,18 @@ def test_fallback_rerun_lands_unchanged_no_reembed(
     try:
         s1 = asyncio.run(import_sources([root], llm, session=db))
         assert (s1.added, s1.pdfs_screenshotted) == (1, 1)
-        assert llm.vision_calls == 2
+        assert llm.vision_calls == 2  # one per page — the first index
         embeds1 = len(llm.calls)
         doc1 = _pdf_doc(db, "stable", "stable.pdf")
         content1, digest1 = doc1.content, doc1.content_hash
 
         s2 = asyncio.run(import_sources([root], llm, session=db))
-        # The fallback re-ran (gate re-fired, vision re-issued) — but
-        # the row itself re-imported as unchanged (no re-embed, no
-        # re-chunk, no KB change: the stable replies give the same
-        # digest, so the upsert is skipped entirely).
+        # The fast path fired (file hash match) — the fallback never
+        # ran on run 2: no gate, no render, no vision re-issued, no
+        # re-embed, no KB change.
         assert (s2.added, s2.updated, s2.unchanged) == (0, 0, 1)
-        assert s2.pdfs_screenshotted == 1  # the gate re-fired
-        assert llm.vision_calls == 4  # the vision calls were re-issued
+        assert s2.pdfs_screenshotted == 0  # the gate never re-fired
+        assert llm.vision_calls == 2  # NO re-issued vision call
         assert len(llm.calls) == embeds1, "unchanged: no re-embed"
         assert s2.changed_paths == [], "unchanged: no KB change recorded"