phase: 163_pdf_strip_additive_selfheal

All gates verified. Final report:

**Phase 163 — final verification pass (all 5 tasks already complete; verification-only run)**

- Verified D1–D4 in code: `page_strip_mode` column + migration 0027, `DocContent` absent-never-null rule keyed off `page_count`; `_persist_pdf_pages` render → atomic tmp+`os.replace` writes → stale-tail-last + `strip_class` stamp; `_regate_pdf_strip` on both unchanged paths (mirror gate, heal, repair, fail-soft, one INFO line only when acting); viewer mode branch + Text/Pages toggle (Text default, `aria-pressed`, no innerHTML, lazy imgs).
- `uv run pytest --cov=app --cov-report=term-missing` → **3796 tests, exit 0, coverage 99%** (>90%)
- `uv run pytest tests/e2e/test_pdf_strip_additive_selfheal.py -v --no-cov` → **5 passed** in isolation
- `test_pdf_pages_in_sources + test_pictorial_pdf + test_garbage_pdf` → 10 passed; `test_document_viewer(_context) + test_image_documents` → 20 passed
- `uv run ruff check .` clean; `uv run pyright` → 0 errors; alembic **0027 downgrade→upgrade CLI round-trip clean** (+ integration pins)
- Completion criteria: additive view w/ toggle ✅ · primary DOM byte-identity ✅ · write-first order/mid-write-failure/atomic pins ✅ · heal + repair E2E ✅ · zero vision/LLM on fast path (mock-captured) ✅ · non-qualifying payload byte-identity ✅ · docs pass ✅
- **Documentation**: README.md + AGENTS.md reviewed in full — the phase's updates are accurate; all config-table defaults cross-checked against `app/config.py` (no drift), every page route, script, and E2E command referenced exists, every `.env.example` var documented — **verified consistent, no changes needed**.
- Notable: live `Letumdei` repair is owner-runtime post-deploy per D5 (next production Sync self-heals; no live changes made); the modified `.agents/screenshots/doc_modal_scrollbar_1280.png` is an E2E-regenerated artifact left for the pipeline commit.
- **Next pending phase:** `164_chat_error_honesty`

tests/integration/test_docs_api.py

@@ -10,7 +10,10 @@ per phase 124 A4) and the phase-148 (task 02) PDF page route
 (``GET /api/documents/{id}/pages/{n}`` — the same trust model and 404
 posture for a page-qualifying document's rendered page PNGs) + the
 content endpoint's ``image_url`` / ``page_urls`` keys (present for the
-qualifying row, ABSENT otherwise — never ``null``).
+qualifying row, ABSENT otherwise — never ``null``), plus the phase-163
+(task 01) ``page_strip_mode`` class signal (``"primary"`` /``"additive"``
+for a stamped strip, ABSENT for a pre-phase row and for every
+non-qualifying document).
 
 Uses the real compose Postgres (``db`` fixture) and FastAPI's TestClient.
 """
@@ -1381,7 +1384,8 @@ def test_content_endpoint_exposes_the_image_affordance(
 
 # ---------------------------------------------------------------------------
 # Phase 148 (task 02) — the PDF page BYTES route + the content payload's
-# ``page_urls`` affordance
+# ``page_urls`` affordance (phase 163 task 01 adds the ``page_strip_mode``
+# class signal beside it)
 # ---------------------------------------------------------------------------
 
 
@@ -1404,6 +1408,7 @@ def _seed_page_doc(
     path: str = "besta.pdf",
     page_count: int | None = 2,
     write_copies: bool = True,
+    page_strip_mode: str | None = None,
 ) -> Document:
     """One PDF document row with ``page_count`` + its rendered page
     copies (the importer's ``pdf_page_dir`` layout —
@@ -1411,7 +1416,8 @@ def _seed_page_doc(
     sentinel bytes, so a page mix-up between the two copies is caught.
     ``page_count=None`` is a non-qualifying PDF (no copies);
     ``write_copies=False`` leaves a qualifying row without its files
-    (the lost-copy corner)."""
+    (the lost-copy corner); ``page_strip_mode`` (phase 163) stamps the
+    strip CLASS — ``None`` is the pre-phase row."""
     doc = Document(
         id=uuid.uuid4(),
         source=source,
@@ -1424,6 +1430,7 @@ def _seed_page_doc(
         created_at=datetime(2026, 1, 1, tzinfo=UTC),
         summary="IKEA BESTA frame assembly manual (page descriptions).",
         page_count=page_count,
+        page_strip_mode=page_strip_mode,
     )
     db.add(doc)
     db.flush()
@@ -1610,6 +1617,79 @@ def test_content_endpoint_exposes_the_page_urls_affordance(
         )
         assert r.status_code == 200
         assert "page_urls" not in r.json()  # absent — never null (non-qualifying PDF)
+        # Phase 163 (task 01): the class key follows the same rule — a
+        # pre-phase row (mode NULL) omits it while keeping page_urls.
+        assert "page_strip_mode" not in r.json()
+    finally:
+        _cleanup_kb(db)
+
+
+@pytest.mark.parametrize("mode", ["primary", "additive"])
+def test_content_endpoint_carries_the_strip_class(
+    admin_client: TestClient, db, tmp_path: Path, mode: str
+) -> None:
+    """Phase 163 (task 01, LOCKED A2/A3) — the real-DB round-trip of the
+    strip CLASS: a stamped row (``page_strip_mode`` = ``"primary"`` — the
+    phase-133 fallback class, the strip IS the view — or ``"additive"`` —
+    the phase-140 pictorial class, text + a Text/Pages toggle) serves the
+    class VERBATIM beside the untouched ``page_urls`` list (the viewer's
+    branch signal, task 04); every other key stands where phase 148 left
+    it."""
+    _cleanup_kb(db)
+    try:
+        pages_dir = tmp_path / "pages"
+        _seed_page_doc(db, pages_dir, page_count=3, page_strip_mode=mode)
+        r = admin_client.get(
+            "/api/documents/content", params={"source": "PdfSrc", "path": "besta.pdf"}
+        )
+        assert r.status_code == 200
+        body = r.json()
+        assert body["page_strip_mode"] == mode
+        assert len(body["page_urls"]) == 3  # the strip rides along, unchanged
+    finally:
+        _cleanup_kb(db)
+
+
+def test_content_strip_class_never_travels_without_the_strip(
+    admin_client: TestClient, db, tmp_path: Path
+) -> None:
+    """Phase 163 (task 01) — the two strip keys are ONE block keyed off
+    ``page_count``: a row with a stray ``page_strip_mode`` and no strip
+    (``page_count`` NULL — the corner a partial repair could leave)
+    serializes NEITHER key, byte-identically to a plain non-qualifying
+    document (the viewer must never be handed a class for pages that do
+    not exist)."""
+    _cleanup_kb(db)
+    try:
+        pages_dir = tmp_path / "pages"
+        _seed_page_doc(
+            db,
+            pages_dir,
+            path="stray.pdf",
+            page_count=None,
+            write_copies=False,
+            page_strip_mode="additive",
+        )
+        r = admin_client.get(
+            "/api/documents/content", params={"source": "PdfSrc", "path": "stray.pdf"}
+        )
+        assert r.status_code == 200
+        body = r.json()
+        assert "page_strip_mode" not in body
+        assert "page_urls" not in body
+        # The exact pre-phase key set (the byte-identity pin).
+        assert set(body) == {
+            "source",
+            "path",
+            "title",
+            "format",
+            "summary",
+            "created_at",
+            "content",
+            "indexed_at",
+            "chunks",
+            "is_image",
+        }
     finally:
         _cleanup_kb(db)