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`

app/models.py

@@ -198,6 +198,24 @@ class Document(Base):
     #: cleanup deletes the copies with the row. No index: a display
     #: fact, never a query surface (the ``file_hash`` convention, 0025).
     page_count: Mapped[int | None] = mapped_column(Integer, default=None)
+    #: The STRIP CLASS behind a non-NULL :py:attr:`page_count` (phase 163,
+    #: LOCKED A1/A3) — the signal the viewer branches on so a text-bearing
+    #: book never loses its text:
+    #:
+    #: * ``"primary"`` — the phase-133 FALLBACK class (unusable text layer:
+    #:   the screenshots ARE the content): the strip IS the view, exactly
+    #:   as phase 148 shipped it;
+    #: * ``"additive"`` — the phase-140 PICTORIAL class (usable text layer,
+    #:   ≥1 sparse page described): the text view + the Summary panel, with
+    #:   the strip one Text/Pages toggle away (Text is the default).
+    #:
+    #: NULL = no strip (every non-qualifying document) — and a pre-phase-163
+    #: row keeps NULL while its ``page_count`` stands, which the wire treats
+    #: as ``"primary"`` (today's DOM) until the fast-path re-gate stamps it.
+    #: Stamped/cleared EXACTLY with ``page_count``: written by the importer's
+    #: persist (task 02) and the unchanged-path re-gate (task 03) only. Like
+    #: ``page_count`` it is a display fact, never a query surface — no index.
+    page_strip_mode: Mapped[str | None] = mapped_column(String(16), default=None)
 
     chunks: Mapped[list[Chunk]] = relationship(
         back_populates="document", cascade="all, delete-orphan"