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/unit/test_document_viewer.py

@@ -30,6 +30,17 @@ page-qualifying PDF row (``page_count`` set) adds ``page_urls`` = the
 exact 1-based ``/api/documents/<id>/pages/<i>`` list over
 ``1..page_count``.
 
+Phase 163 (task 01) — the content payload's STRIP CLASS signal
+(``page_strip_mode``: ``"primary"`` = the fallback class, the strip IS
+the view; ``"additive"`` = the pictorial class, text + a Text/Pages
+toggle): the model-level omission rule (ABSENT when ``None``, never
+``null``), and the endpoint (stubbed session) — the key rides
+``page_urls`` for a qualifying row, a PRE-PHASE row (``page_count`` set,
+mode NULL — the exact live ``Letumdei`` state) serializes it ABSENT while
+keeping ``page_urls``, and the whole strip block keys off
+``page_count``, so a row with a stray mode and no strip carries neither
+key (every non-qualifying payload byte-identical to pre-phase).
+
 Phase 145 (task 03) — the content payload's git origin fields + the
 ``renderDocument`` "Original" anchor (modal AND /document.html, one
 site):
@@ -316,10 +327,11 @@ def _text_doc_content(
     origin_url: str | None = None,
     origin_branch: str | None = None,
     page_urls: list[str] | None = None,
+    page_strip_mode: str | None = None,
 ) -> DocContent:
     """One text doc's content payload (the pre-phase shape) with the
-    phase-145 origin fields + the phase-148 ``page_urls`` optionally
-    set."""
+    phase-145 origin fields + the phase-148 ``page_urls`` + the
+    phase-163 ``page_strip_mode`` optionally set."""
     return DocContent(
         source="S",
         path="a.md",
@@ -332,6 +344,7 @@ def _text_doc_content(
         origin_url=origin_url,
         origin_branch=origin_branch,
         page_urls=page_urls,
+        page_strip_mode=page_strip_mode,
     )
 
 
@@ -367,9 +380,29 @@ def test_doc_content_page_urls_absent_on_the_wire_when_unset() -> None:
     assert dumped["page_urls"] == urls  # the exact 1-based route list
 
 
-def _page_pdf_doc() -> Document:
+def test_doc_content_page_strip_mode_absent_on_the_wire_when_unset() -> None:
+    """Phase 163 (task 01, LOCKED A2) — the model-level omission rule
+    (the ``image_url`` / ``page_urls`` precedent): no strip class
+    (``page_strip_mode`` ``None`` — every non-qualifying doc AND every
+    pre-phase row) serializes the key ABSENT — never ``null`` — so those
+    payloads are byte-identical to pre-phase. A stamped row carries the
+    class verbatim, beside ``page_urls``."""
+    dumped = _text_doc_content().model_dump()
+    assert "page_strip_mode" not in dumped  # absent — never null
+    for mode in ("primary", "additive"):
+        dumped = _text_doc_content(
+            page_urls=["/api/documents/d/pages/1"], page_strip_mode=mode
+        ).model_dump()
+        assert dumped["page_strip_mode"] == mode  # the class verbatim
+
+
+def _page_pdf_doc(
+    page_count: int | None = 2, page_strip_mode: str | None = None
+) -> Document:
     """A page-QUALIFYING PDF row (phase 148): ``page_count`` set — the
-    endpoint derives ``page_urls`` from it (the exact 1-based list)."""
+    endpoint derives ``page_urls`` from it (the exact 1-based list).
+    ``page_strip_mode`` (phase 163) is the strip CLASS; ``None`` is the
+    PRE-PHASE row shape (the column NULL while the strip stands)."""
     doc = Document(
         id=uuid.uuid4(),
         source="Homelab",
@@ -379,7 +412,8 @@ def _page_pdf_doc() -> Document:
         content="[Page 1 illustration: the parts tray]…",
         content_hash="e" * 64,
         is_image=False,  # phase 122: the stub session never applies defaults
-        page_count=2,
+        page_count=page_count,
+        page_strip_mode=page_strip_mode,
     )
     doc.indexed_at = datetime(2026, 8, 22, 1, 2, 3, tzinfo=UTC)
     doc.created_at = datetime(2026, 8, 20, 9, 0, 0, tzinfo=UTC)
@@ -410,6 +444,79 @@ database): a page-qualifying PDF row (``page_count`` set) carries
     ]  # the exact 1-based list, count == page_count
     assert body["is_image"] is False
     assert "image_url" not in body  # absent — never null (not an image doc)
+    # Phase 163 (task 01): the pre-phase row (mode NULL) keeps the strip
+    # and serializes the class ABSENT — the viewer treats that as
+    # "primary", i.e. today's DOM.
+    assert "page_strip_mode" not in body
+
+
+@pytest.mark.parametrize("mode", ["primary", "additive"])
+def test_content_page_strip_mode_carried_for_a_stamped_strip(mode: str) -> None:
+    """Phase 163 (task 01, LOCKED A2/A3) — the endpoint (stubbed
+session, no
+database): a page-qualifying PDF whose row carries the class
+    (``"primary"`` = the fallback class, ``"additive"`` = the pictorial
+    class) carries ``page_strip_mode`` VERBATIM next to ``page_urls`` —
+    the signal the viewer branches on so an additive strip never hides
+    the text (task 04). Nothing else in the payload moves."""
+    doc = _page_pdf_doc(page_strip_mode=mode)
+    with _client_with_row((doc, 4)) as client:
+        r = client.get(
+            "/api/documents/content",
+            params={"source": "Homelab", "path": "ikea/besta.pdf"},
+        )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["page_strip_mode"] == mode  # the class verbatim
+    assert body["page_urls"] == [
+        f"/api/documents/{doc.id}/pages/1",
+        f"/api/documents/{doc.id}/pages/2",
+    ]  # the strip rides along, unchanged
+
+
+def test_content_strip_block_keys_off_page_count_never_mode_alone() -> None:
+    """Phase 163 (task 01) — the class never appears alone: the whole
+    strip block keys off ``page_count``, so a row whose column somehow
+    holds a mode while ``page_count`` is NULL serializes NEITHER
+    ``page_strip_mode`` nor ``page_urls`` — the payload is byte-identical
+    to a plain non-qualifying document (there is no strip to show, and
+    the viewer must never be told a class for pages that do not exist)."""
+    doc = _page_pdf_doc(page_count=None, page_strip_mode="additive")
+    with _client_with_row((doc, 1)) as client:
+        r = client.get(
+            "/api/documents/content",
+            params={"source": "Homelab", "path": "ikea/besta.pdf"},
+        )
+    assert r.status_code == 200
+    body = r.json()
+    assert "page_strip_mode" not in body  # absent — the strip block is off
+    assert "page_urls" not in body  # absent — never null
+
+
+def test_content_non_qualifying_payload_key_set_is_byte_identical() -> None:
+    """Phase 163 (task 01) — the byte-identity pin: a non-qualifying PDF
+    row (``page_count`` NULL, mode NULL) carries EXACTLY the pre-phase
+    key set — neither strip key joins it (``is_image`` always present,
+    ``image_url`` / the origin keys / both strip keys absent)."""
+    doc = _page_pdf_doc(page_count=None)
+    with _client_with_row((doc, 1)) as client:
+        r = client.get(
+            "/api/documents/content",
+            params={"source": "Homelab", "path": "ikea/besta.pdf"},
+        )
+    assert r.status_code == 200
+    assert set(r.json()) == {
+        "source",
+        "path",
+        "title",
+        "format",
+        "summary",
+        "created_at",
+        "content",
+        "indexed_at",
+        "chunks",
+        "is_image",
+    }
 
 
 def test_content_origin_url_carried_for_a_matching_git_row() -> None:

tests/unit/test_importer_unchanged_fast_path.py

@@ -31,6 +31,16 @@ the second sync):
 * the streamed hash is transparent (a >1 MiB file hashes identically
   to ``hashlib.sha256(bytes).hexdigest()``).
 
+Phase 163 (task 03) extends this file with the PDF strip RE-GATE the
+unchanged paths now run (``_regate_pdf_strip``) — the pre-phase "the
+copies persist" assumption is what broke in production (a row claiming
+``page_count = 36`` over ZERO files, every page 404ing forever): the
+re-gate re-derives the strip from the current bytes + settings (ZERO
+vision/LLM calls), heals missing copies, re-stamps a changed class,
+clears a strip that no longer qualifies (kill switch included), stays
+fail-soft, logs only when it ACTS, and costs a non-strip file zero PDF
+parsing (spy-pinned).
+
 The E2E surface (the idempotent second sync through the real UI +
 mock LLM) is pinned in ``tests/e2e/test_sync_changed_only.py``
 (task 03).
@@ -43,6 +53,7 @@ import logging
 import os
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
+from typing import Any
 
 import pymupdf as fitz
 import pytest
@@ -50,6 +61,7 @@ from sqlalchemy import select
 
 from app.config import Settings
 from app.models import Document
+from app.rag import importer
 from app.rag.importer import _file_hash, import_sources
 from tests.fakes import FakeEmbedder
 from tests.unit.test_importer import (
@@ -60,6 +72,7 @@ from tests.unit.test_importer import (
     _VisionLLM,
 )
 from tests.unit.test_pictorial_import import (
+    _build_dense_pdf,
     _build_ikea_like_pdf,
     _PictorialLLM,
     _settings,
@@ -454,6 +467,520 @@ def test_pre_phase_null_file_hash_image_runs_branch_and_stamps(
         _cleanup_source(db, root.name)
 
 
+# ---------- phase 163 (task 03): the deterministic PDF strip re-gate ----------
+#
+# The live defect (owner report, 2026-10-07): the `Letumdei` row carried
+# `page_count = 36` over ZERO files on disk (the pre-phase-163 persist
+# deleted the old copies BEFORE rendering, outside the DB transaction —
+# a later per-file rollback restored the stale count over an empty
+# directory; an external wipe of `pdf_page_dir` lands the same state).
+# The phase-147 fast path believed "the copies persist" and never
+# re-rendered, so the strip 404'd forever. `_regate_pdf_strip` now runs
+# at the tail of `_unchanged_doc`: the changed-path gate mirrored from
+# the current bytes + settings (ZERO vision/LLM calls), missing copies
+# healed, a stale strip cleared.
+
+#: The PNG signature (a healed copy is a real render, not a placeholder).
+PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+
+
+def _regate_settings(tmp_path: Path, **kwargs: Any) -> Settings:
+    """Settings for the re-gate matrix: the ``pdf`` token admitted, the
+    phase-140 knobs at their CODE DEFAULTS (``pdf_pictorial`` ON), and
+    the strip's home ``pdf_page_dir`` pinned under *tmp_path* (never the
+    real home)."""
+    kwargs.setdefault("_env_file", None)
+    kwargs.setdefault("import_extensions", "md,txt,pdf")
+    kwargs.setdefault("images", False)
+    kwargs.setdefault("image_dir", str(tmp_path / "images"))
+    kwargs.setdefault("pdf_page_dir", str(tmp_path / "pages"))
+    return Settings(**kwargs)  # pyright: ignore[reportCallIssue]
+
+
+def _pages_dir(tmp_path: Path) -> Path:
+    return tmp_path / "pages"
+
+
+def _strip_copies(doc: Document, page_dir: Path, count: int) -> list[Path]:
+    return [page_dir / f"{doc.id}-p{n}.png" for n in range(1, count + 1)]
+
+
+def test_regate_heals_deleted_copies_of_a_pictorial_strip(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """THE live-loss reproduction (heal arm): a pictorial-class PDF is
+    indexed (``page_count`` set, copies written), its copies are deleted
+    out from under the row (the exact live state — mode NULL on a
+    pre-phase row), and an UNCHANGED re-sync restores every file with
+    real PNG bytes, stamps the mode ``additive``, keeps ``page_count``
+    (no drift), burns ZERO llm/vision calls, and logs the one greppable
+    INFO line. The NULL-mode stamp is SILENT (no ``mode`` segment — it
+    rides the line only when work followed)."""
+    root = tmp_path / "rgheal"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgheal", "ikea.pdf")
+        assert (doc.page_count, doc.page_strip_mode) == (10, "additive")
+        page_dir = _pages_dir(tmp_path)
+        doc.page_strip_mode = None  # the pre-phase row (the live shape)
+        db.commit()
+        for path in _strip_copies(doc, page_dir, 10):
+            path.unlink()
+        assert not list(page_dir.glob(f"{doc.id}-*.png"))
+        embeds1, chats1, vision1 = len(llm.calls), len(llm.chat_calls), llm.pictorial_calls
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        # ZERO llm work of any kind (the re-gate is deterministic, A5).
+        assert len(llm.calls) == embeds1, "the re-gate never re-embeds"
+        assert len(llm.chat_calls) == chats1, "the re-gate never chats"
+        assert llm.pictorial_calls == vision1, "the re-gate issues ZERO vision calls"
+
+        db.expire_all()
+        doc2 = _doc(db, "rgheal", "ikea.pdf")
+        assert doc2.page_count == 10, "no drift — the count is untouched"
+        assert doc2.page_strip_mode == "additive", "the mode is stamped"
+        for path in _strip_copies(doc2, page_dir, 10):
+            assert path.is_file(), f"copy {path.name} was not healed"
+            assert path.read_bytes()[:8] == PNG_MAGIC, f"{path.name} is not a PNG"
+        assert not list(page_dir.glob("*.tmp")), "no .tmp orphan from the heal"
+        messages = [r.getMessage() for r in caplog.records]
+        assert (
+            "import: PDF strip re-gate source=rgheal path=ikea.pdf — "
+            "healed 10 pages"
+        ) in messages, messages
+        assert not any("mode " in m for m in messages if "re-gate" in m), (
+            "a NULL->stamp mode re-stamp is silent-beneficial " + str(messages)
+        )
+    finally:
+        _cleanup_source(db, "rgheal")
+
+
+def test_regate_heals_a_fallback_strip_as_primary(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Heal arm, the FALLBACK class (phase 133's unusable text layer):
+    the copies of a garbage-layer PDF's strip are restored on an
+    unchanged re-sync and the mode lands ``primary`` (the strip IS the
+    view) — and the phase-133 fallback vision does NOT re-fire (the
+    class is re-derived from the bytes, no vision call)."""
+    root = tmp_path / "rgfall"
+    root.mkdir()
+    _build_garbage_pdf(root / "garbage.pdf")  # 2 pages
+    llm = _PageVisionLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgfall", "garbage.pdf")
+        assert (doc.page_count, doc.page_strip_mode) == (2, "primary")
+        page_dir = _pages_dir(tmp_path)
+        for path in _strip_copies(doc, page_dir, 2):
+            path.unlink()
+        vision1, chats1, embeds1 = llm.vision_calls, len(llm.chat_calls), len(llm.calls)
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        assert second.pdfs_screenshotted == 0, "the fallback gate did not re-run"
+        assert llm.vision_calls == vision1, "ZERO vision calls on the re-gate"
+        assert len(llm.chat_calls) == chats1 and len(llm.calls) == embeds1
+
+        db.expire_all()
+        doc2 = _doc(db, "rgfall", "garbage.pdf")
+        assert doc2.page_strip_mode == "primary", "the unusable layer is primary"
+        assert doc2.page_count == 2
+        for path in _strip_copies(doc2, page_dir, 2):
+            assert path.is_file() and path.read_bytes()[:8] == PNG_MAGIC
+        assert any(
+            "healed 2 pages" in m and "re-gate" in m for m in caplog.messages
+        ), caplog.messages
+    finally:
+        _cleanup_source(db, "rgfall")
+
+
+def test_regate_noop_when_the_strip_is_healthy(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """No-op arm (the IKEA-class doc whose copies all stand): an
+    unchanged re-sync writes NOTHING (every copy's mtime and bytes are
+    untouched), renders NOTHING, and logs NO re-gate line — the INFO is
+    never per-unchanged-doc — while the pre-existing ``import:
+    unchanged`` line still fires."""
+    root = tmp_path / "rgnoop"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgnoop", "ikea.pdf")
+        page_dir = _pages_dir(tmp_path)
+        before = {
+            p: (p.stat().st_mtime_ns, p.read_bytes())
+            for p in _strip_copies(doc, page_dir, 10)
+        }
+        assert len(before) == 10
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        db.expire_all()
+        doc2 = _doc(db, "rgnoop", "ikea.pdf")
+        assert (doc2.page_count, doc2.page_strip_mode) == (10, "additive")
+        after = {
+            p: (p.stat().st_mtime_ns, p.read_bytes())
+            for p in _strip_copies(doc2, page_dir, 10)
+        }
+        assert after == before, "a healthy strip is not written at all"
+        messages = [r.getMessage() for r in caplog.records]
+        assert any(m.startswith("import: unchanged ") for m in messages), messages
+        assert not any("re-gate" in m for m in messages), (
+            f"the re-gate logged without acting: {messages}"
+        )
+    finally:
+        _cleanup_source(db, "rgnoop")
+
+
+def test_regate_restamps_a_changed_mode(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Mode re-stamp (the class flip): a row whose stamped mode no
+    longer matches the gate's class (here a pictorial-class row carrying
+    ``primary`` — a legacy/mis-stamped row) is re-stamped to
+    ``additive``, and because the mode was ALREADY SET the change is
+    reported (``mode primary->additive``) — the only thing the re-gate
+    did, so that is the whole INFO line (no copies were missing, none
+    were written)."""
+    root = tmp_path / "rgmode"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgmode", "ikea.pdf")
+        assert doc.page_strip_mode == "additive"
+        doc.page_strip_mode = "primary"  # the mis-stamp the re-gate fixes
+        db.commit()
+        page_dir = _pages_dir(tmp_path)
+        before = {
+            p: p.stat().st_mtime_ns for p in _strip_copies(doc, page_dir, 10)
+        }
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.unchanged) == (0, 1)
+        db.expire_all()
+        doc2 = _doc(db, "rgmode", "ikea.pdf")
+        assert doc2.page_strip_mode == "additive", "the class is re-stamped"
+        assert doc2.page_count == 10
+        assert {
+            p: p.stat().st_mtime_ns for p in _strip_copies(doc2, page_dir, 10)
+        } == before, "a mode fix writes no files"
+        assert (
+            "import: PDF strip re-gate source=rgmode path=ikea.pdf — "
+            "mode primary->additive"
+        ) in [r.getMessage() for r in caplog.records], caplog.messages
+    finally:
+        _cleanup_source(db, "rgmode")
+
+
+def test_regate_clears_a_strip_that_no_longer_qualifies(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """REPAIR arm: a row claims a strip (``page_count`` set, copies on
+    disk) on a PDF whose GATE now says ineligible (a clean, dense text
+    layer — zero sparse pages). The unchanged re-sync clears BOTH
+    columns and deletes the copies (the strip must not linger over a
+    document the viewer shows as text) + the ``cleared stale strip``
+    INFO line, with zero llm calls."""
+    root = tmp_path / "rgclear"
+    root.mkdir()
+    pdf = root / "clean.pdf"
+    _build_dense_pdf(pdf)  # usable layer, zero candidates — never qualifies
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgclear", "clean.pdf")
+        assert (doc.page_count, doc.page_strip_mode) == (None, None)
+        # The stale state the re-gate must repair (a strip stamped by an
+        # older gate/settings, copies still on disk).
+        page_dir = _pages_dir(tmp_path)
+        page_dir.mkdir(parents=True, exist_ok=True)
+        for path in _strip_copies(doc, page_dir, 2):
+            path.write_bytes(b"STALE-COPY")
+        doc.page_count = 2
+        doc.page_strip_mode = "additive"
+        db.commit()
+        embeds1, chats1 = len(llm.calls), len(llm.chat_calls)
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        assert len(llm.calls) == embeds1 and len(llm.chat_calls) == chats1
+
+        db.expire_all()
+        doc2 = _doc(db, "rgclear", "clean.pdf")
+        assert doc2.page_count is None, "the stale strip is cleared"
+        assert doc2.page_strip_mode is None, "the class is cleared with it"
+        assert not list(page_dir.glob(f"{doc2.id}-p*.png")), "the copies are deleted"
+        assert (
+            "import: PDF strip re-gate source=rgclear path=clean.pdf — "
+            "cleared stale strip"
+        ) in [r.getMessage() for r in caplog.records], caplog.messages
+    finally:
+        _cleanup_source(db, "rgclear")
+
+
+def test_regate_kill_switch_clears_the_pictorial_strip(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """REPAIR arm via the kill switch (``pdf_pictorial=False``): the
+    changed-path semantics mirrored — with the pass off a sparse-page
+    PDF is NOT eligible, so its existing strip is cleared with its
+    copies on the next (unchanged) sync. The bytes never moved: the
+    setting alone decided."""
+    root = tmp_path / "rgkill"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgkill", "ikea.pdf")
+        assert (doc.page_count, doc.page_strip_mode) == (10, "additive")
+        page_dir = _pages_dir(tmp_path)
+        assert len(list(page_dir.glob(f"{doc.id}-p*.png"))) == 10
+        vision1 = llm.pictorial_calls
+
+        llm.settings = _regate_settings(tmp_path, pdf_pictorial=False)
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        assert llm.pictorial_calls == vision1, "ZERO vision calls (the pass is off)"
+        db.expire_all()
+        doc2 = _doc(db, "rgkill", "ikea.pdf")
+        assert doc2.page_count is None and doc2.page_strip_mode is None
+        assert not list(page_dir.glob(f"{doc2.id}-p*.png")), "the copies went too"
+        assert any(
+            "cleared stale strip" in m for m in caplog.messages
+        ), caplog.messages
+    finally:
+        _cleanup_source(db, "rgkill")
+
+
+def test_regate_render_exception_is_fail_soft(
+    db,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Fail-soft: the heal's render RAISES — the sync completes
+    (``unchanged``, zero errors), the row keeps its prior state
+    (``page_count`` + mode untouched — the re-gate never clears a strip
+    on a failure), no copies are touched, and the WARNING is the only
+    signal."""
+    root = tmp_path / "rgboom"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgboom", "ikea.pdf")
+        page_dir = _pages_dir(tmp_path)
+        for path in _strip_copies(doc, page_dir, 10):
+            path.unlink()
+
+        def boom(*args: object, **kwargs: object) -> list[bytes]:
+            raise RuntimeError("simulated render failure (test sentinel)")
+
+        monkeypatch.setattr(importer, "render_pdf_pages", boom)
+        with caplog.at_level(logging.WARNING, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged, second.errors) == (
+            0, 0, 1, 0,
+        )
+        db.expire_all()
+        doc2 = _doc(db, "rgboom", "ikea.pdf")
+        assert (doc2.page_count, doc2.page_strip_mode) == (10, "additive"), (
+            "the row keeps its pre-re-gate state"
+        )
+        assert not list(page_dir.glob(f"{doc.id}-p*.png")), "no copies were touched"
+        assert any(
+            "PDF strip re-gate failed" in m and "test sentinel" in m
+            for m in caplog.messages
+        ), caplog.messages
+    finally:
+        _cleanup_source(db, "rgboom")
+
+
+def test_regate_empty_render_keeps_the_row(
+    db,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Fail-soft on the no-pages render (unopenable right after the fast
+    path hashed the file — pathological): the row is kept EXACTLY as it
+    was (never cleared on a transient), nothing is written, and the
+    WARNING names the no-pages state."""
+    root = tmp_path / "rgempty"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgempty", "ikea.pdf")
+        page_dir = _pages_dir(tmp_path)
+        for path in _strip_copies(doc, page_dir, 10):
+            path.unlink()
+        monkeypatch.setattr(importer, "render_pdf_pages", lambda *a, **k: [])
+
+        with caplog.at_level(logging.WARNING, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.unchanged, second.errors) == (0, 1, 0)
+        db.expire_all()
+        doc2 = _doc(db, "rgempty", "ikea.pdf")
+        assert (doc2.page_count, doc2.page_strip_mode) == (10, "additive")
+        assert not page_dir.exists() or not list(page_dir.glob(f"{doc.id}-*"))
+        assert any(
+            "re-render produced no pages (state kept)" in m
+            for m in caplog.messages
+        ), caplog.messages
+    finally:
+        _cleanup_source(db, "rgempty")
+
+
+def test_regate_reports_a_page_count_drift_on_the_heal(
+    db,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Drift (pathological on unchanged bytes, so it is LOUD): the heal
+    renders 6 pages for a row that claimed 10 — ``page_count`` follows
+    the fresh render, the ``p7..p10`` tail beyond it is deleted, and a
+    WARNING names both counts beside the ``healed`` INFO line."""
+    root = tmp_path / "rgdrift"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgdrift", "ikea.pdf")
+        page_dir = _pages_dir(tmp_path)
+        for path in _strip_copies(doc, page_dir, 10):
+            path.unlink()
+        monkeypatch.setattr(
+            importer,
+            "render_pdf_pages",
+            lambda *a, **k: [PNG_MAGIC + f"{i}".encode() for i in range(6)],
+        )
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.unchanged) == (0, 1)
+        db.expire_all()
+        doc2 = _doc(db, "rgdrift", "ikea.pdf")
+        assert doc2.page_count == 6, "the count follows the fresh render"
+        for n in range(1, 7):
+            assert (page_dir / f"{doc2.id}-p{n}.png").is_file()
+        for n in range(7, 11):
+            assert not (page_dir / f"{doc2.id}-p{n}.png").exists(), f"p{n} leaked"
+        messages = [r.getMessage() for r in caplog.records]
+        assert any("page_count drift 10->6" in m for m in messages), messages
+        assert any("healed 10 pages" in m for m in messages), messages
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+        _cleanup_source(db, "rgdrift")
+
+
+def test_regate_fires_on_the_content_digest_hit_path(
+    db, tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """The SECOND unchanged path (the PDF branch's content-digest hit —
+    a pre-phase row with ``file_hash`` NULL): the branch re-runs its own
+    gate (the byte-change's honest cost) and lands unchanged, and the
+    shared helper's tail still heals the strip deleted out from under
+    the row — the re-gate is not fast-path-only."""
+    root = tmp_path / "rgbranch"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        doc = _doc(db, "rgbranch", "ikea.pdf")
+        doc.file_hash = None  # the pre-phase row: the fast path cannot fire
+        db.commit()
+        page_dir = _pages_dir(tmp_path)
+        for path in _strip_copies(doc, page_dir, 10):
+            path.unlink()
+
+        with caplog.at_level(logging.INFO, logger="app.importer"):
+            second = asyncio.run(import_sources([root], llm, session=db))
+
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 1)
+        db.expire_all()
+        doc2 = _doc(db, "rgbranch", "ikea.pdf")
+        assert doc2.file_hash is not None, "the helper stamped the hash"
+        for path in _strip_copies(doc2, page_dir, 10):
+            assert path.is_file(), f"copy {path.name} was not healed"
+        assert any("healed 10 pages" in m for m in caplog.messages), caplog.messages
+    finally:
+        _cleanup_source(db, "rgbranch")
+
+
+def test_regate_guard_costs_a_non_strip_file_nothing(
+    db, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The GUARD (A5): a non-PDF unchanged file and a PDF whose
+    ``page_count`` is NULL reach the tail of ``_unchanged_doc`` and
+    ``extract_pdf_text`` is NEVER called for either — every non-strip
+    file's fast path keeps its zero-extra-read contract (one sync of
+    each class, then the spy covers the second sync only)."""
+    root = tmp_path / "rgguard"
+    root.mkdir()
+    (root / "note.md").write_text("# Note\n\nplain text body\n")
+    _build_dense_pdf(root / "clean.pdf")  # usable layer, no strip
+    llm = _PictorialLLM()
+    llm.settings = _regate_settings(tmp_path)
+    seen: list[str] = []
+    real_extract = importer.extract_pdf_text
+
+    def spy(path: Path) -> str:
+        seen.append(str(path))
+        return real_extract(path)
+
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+        monkeypatch.setattr(importer, "extract_pdf_text", spy)
+        second = asyncio.run(import_sources([root], llm, session=db))
+        assert (second.added, second.updated, second.unchanged) == (0, 0, 2)
+        assert seen == [], f"the guard let a PDF parse through: {seen}"
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+        _cleanup_source(db, "rgguard")
+
+
 # ---------- the preserved semantics on the fast path --------------------------
 
 

tests/unit/test_models.py

@@ -293,6 +293,82 @@ def test_git_source_python_default_include_hidden_false() -> None:
     assert col.default.arg is False, "the default must resolve to False"
 
 
+def test_documents_page_strip_mode_column_contract() -> None:
+    """Phase 163 (task 01): ``documents.page_strip_mode`` — the CLASS of
+    the page strip a non-NULL ``page_count`` describes (``"primary"`` =
+    the phase-133 fallback class, the strip IS the view; ``"additive"``
+    = the phase-140 pictorial class, text + a Text/Pages toggle):
+    VARCHAR(16), NULLABLE (NULL = no strip — and the pre-phase shape for
+    a row whose strip stands), NO server default, and NO index (the
+    content endpoint reads it from the ROW — a display fact, never a
+    query surface, the ``file_hash`` / ``page_count`` convention).
+    ``page_count`` (0026) stays exactly as phase 148 left it."""
+    from sqlalchemy import String as SAString
+
+    documents = Base.metadata.tables["documents"]
+    assert "page_strip_mode" in documents.c, (
+        "documents must have the page_strip_mode column (phase 163)"
+    )
+    col = documents.c["page_strip_mode"]
+    assert col.nullable is True, (
+        "page_strip_mode must be NULLABLE — NULL means no strip (and the"
+        " pre-phase row whose strip stands)"
+    )
+    assert isinstance(col.type, SAString), "page_strip_mode must be a String column"
+    assert col.type.length == 16, (
+        "page_strip_mode must be String(16) — the two class names, bounded"
+    )
+    assert col.server_default is None, (
+        "page_strip_mode must carry NO server default — NULL is the"
+        " meaningful pre-phase state"
+    )
+    assert not col.index, (
+        "page_strip_mode must be UNINDEXED — the content endpoint reads it"
+        " from the row, no query filters on it"
+    )
+    covering = [
+        idx
+        for idx in documents.indexes
+        if any(c.name == "page_strip_mode" for c in idx.columns)
+    ]
+    assert not covering, "no table-level index may cover page_strip_mode"
+
+    # page_count is untouched: still the nullable, unindexed sibling.
+    page_count = documents.c["page_count"]
+    assert page_count.nullable is True, "page_count must stay NULLABLE (0026)"
+    assert not page_count.index, "page_count must stay UNINDEXED (0026)"
+
+
+def test_document_page_strip_mode_orm_defaults_to_none() -> None:
+    """A freshly constructed ``Document`` (no DB) exposes
+    ``page_strip_mode``: an omitted kwarg and an explicit ``None`` both
+    read NULL (no strip — the shape every non-qualifying document keeps,
+    and the shape a pre-phase-163 row keeps WHILE its ``page_count``
+    stands, which the wire serializes ABSENT), and each class name
+    round-trips verbatim as a plain string (the real DB round-trip is
+    pinned in ``test_migration_0027.py``)."""
+    from app.models import Document
+
+    base = dict(
+        source="s",
+        path="p.pdf",
+        full_path="/tmp/s/p.pdf",
+        title="p",
+        content="c",
+        content_hash="1" * 64,
+        page_count=36,
+    )
+    for mode in ("primary", "additive"):
+        assert Document(**base, page_strip_mode=mode).page_strip_mode == mode
+
+    assert Document(**base, page_strip_mode=None).page_strip_mode is None
+    omitted = Document(**base)
+    assert omitted.page_strip_mode is None, (
+        "an omitted page_strip_mode must read NULL while page_count stands"
+        " (the pre-phase strip the viewer keeps showing as 'primary')"
+    )
+
+
 def test_doc_drafts_column_contract() -> None:
     """Phase 59: the editable triple (title/path/body) + status +
     timestamps are NOT NULL; ``branch`` / ``commit_sha`` are NULL

tests/unit/test_pdf_page_copies.py

@@ -21,14 +21,20 @@ builder for the negative; the copies land in a tmp ``pdf_page_dir``):
   layer, ≥1 sparse page) and the fallback class (unusable layer) get
   ``<doc-id>-p{N}.png`` for EVERY page (not just the described
   candidates — the strip shows the whole manual) + ``page_count`` =
-  the page count + real PNG bytes; a text-heavy PDF gets neither
-  (no copies, NULL count, ZERO render calls, byte-identical content);
+  the page count + real PNG bytes + the phase-163 CLASS stamp
+  (``page_strip_mode`` ``additive`` / ``primary``); a text-heavy PDF
+  gets neither (no copies, NULL count, NULL mode, ZERO render calls,
+  byte-identical content);
 * the phase-147 fast path — an unchanged qualifying PDF's second sync
   re-renders NOTHING (zero render calls — the copies persist,
   ``page_count`` and the bytes untouched);
-* stale replacement — a changed (shrunk) PDF's old copy set is
-  replaced: the new set covers the new pages, the old ``p{N}`` tail
-  is GONE (no orphans), ``page_count`` follows the new count;
+* WRITE-FIRST replacement (phase 163, task 02, LOCKED A4) — a changed
+  (shrunk) PDF's new copies land atomically (tmp + ``os.replace``,
+  pinned) BEFORE any old copy is removed; the old ``p{N}`` tail is
+  GONE only after the replacement bytes are durable (no orphans),
+  ``page_count`` follows the new count; a MID-WRITE failure leaves the
+  prior copy set intact (the rollback-orphan state — the row over
+  zero files — is structurally unrepresentable);
 * qualifier loss — a qualifying PDF whose new version gained a dense
   text layer loses its strip: ``page_count`` NULL + copies deleted;
 * unopenable — a render that yields no pages (``render_pdf_pages`` →
@@ -40,9 +46,10 @@ builder for the negative; the copies land in a tmp ``pdf_page_dir``):
   the FULL count (the gap is a display-level 404 — task 02 pins the
   route's side);
 * fail-soft — the render raising (warning is the signal, ``page_count``
-  NULL, no copies, the doc indexed fully — chunks + summary) and the
-  WRITER raising (the copies this call wrote are removed — no partial
-  orphans, ``page_count`` NULL, the doc indexed fully);
+  + ``page_strip_mode`` NULL, no copies, the doc indexed fully — chunks
+  + summary) and the WRITER raising (this call's ``.tmp`` files and the
+  finals it CREATED are removed — no partial orphans, ``page_count`` +
+  ``page_strip_mode`` NULL, the doc indexed fully);
 * prune — a qualifying doc's file removed from the source: the row
   goes and its page copies go with it (no orphans in the tmp dir).
 
@@ -54,6 +61,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
 import uuid
 from collections.abc import Callable, Sequence
 from pathlib import Path
@@ -161,6 +169,35 @@ def _render_spy(
     return calls
 
 
+# ---------------------------------------------------------------------------
+# Phase 163 (task 01) — the strip-class column beside page_count
+# ---------------------------------------------------------------------------
+
+
+def test_pictorial_index_stamps_the_additive_class(db, tmp_path: Path) -> None:
+    """Phase 163 (task 02, re-cut of the task-01 pin) — the STAMP: a
+    qualifying PDF indexed through the PICTORIAL class gets
+    ``page_strip_mode == "additive"`` beside ``page_count`` (the text +
+    toggle view); the strip's copies themselves are unchanged by the
+    phase (task 01's shape, mode stamped exactly with the count).
+    """
+    root = tmp_path / "pgm"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _settings(tmp_path)
+    try:
+        summary = asyncio.run(import_sources([root], llm, session=db))
+        assert (summary.files, summary.added, summary.errors) == (1, 1, 0)
+        doc = _doc(db, "pgm", "ikea.pdf")
+        assert doc.page_count == 10, "the strip itself is unchanged by task 02"
+        assert doc.page_strip_mode == "additive", (
+            "the pictorial class stamps the additive mode (LOCKED A1/A3)"
+        )
+    finally:
+        _cleanup_source(db, "pgm")
+
+
 # ---------------------------------------------------------------------------
 # Eligibility × new index
 # ---------------------------------------------------------------------------
@@ -219,6 +256,10 @@ def test_fallback_class_garbage_pdf_writes_every_page_copy(db, tmp_path: Path) -
         assert summary.pdfs_screenshotted == 1  # the fallback fired (the class)
         doc = _doc(db, "pgf", "garbage.pdf")
         assert doc.page_count == 2
+        assert doc.page_strip_mode == "primary", (
+            "the fallback class stamps the primary mode — the strip IS the "
+            "view, byte-identical to phase 148 otherwise (LOCKED A1)"
+        )
         page_dir = _pages_dir(tmp_path)
         for n in (1, 2):
             path = page_dir / f"{doc.id}-p{n}.png"
@@ -253,6 +294,7 @@ def test_text_heavy_pdf_keeps_the_text_view(
         assert summary.pdfs_pictorial == 0  # zero candidates — the pass no-ops
         doc = _doc(db, "pgd", "clean.pdf")
         assert doc.page_count is None, "a text-heavy PDF keeps the text view"
+        assert doc.page_strip_mode is None, "no strip — no class either"
         assert not _pages_dir(tmp_path).exists(), "no copies — the dir is never created"
         assert calls == [], "zero render calls (no fallback, zero candidates)"
         assert doc.content == expected, "byte-identical to the extraction"
@@ -315,9 +357,10 @@ def test_changed_pdf_replaces_the_copy_set_without_orphans(
 ) -> None:
     """A CHANGED (shrunk, 10 → 6 pages) qualifying PDF: the re-index
     replaces the copy set — the new set covers p1..p6, the old
-    version's ``p7..p10`` tail is GONE (the stale-replacement runs
-    before the write), the doc keeps its id, and ``page_count``
-    follows the new page count."""
+    version's ``p7..p10`` tail is GONE (the stale-tail delete runs
+    LAST, after the write-first loop — phase 163, task 02), the doc
+    keeps its id, ``page_count`` follows the new page count, and
+    ``page_strip_mode`` is (re-)stamped."""
     root = tmp_path / "pgc"
     root.mkdir()
     pdf = root / "ikea.pdf"
@@ -336,6 +379,7 @@ def test_changed_pdf_replaces_the_copy_set_without_orphans(
         doc2 = _doc(db, "pgc", "ikea.pdf")
         assert doc2.id == doc1.id, "the doc keeps its id (the copy path is stable)"
         assert doc2.page_count == 6, "page_count follows the new page count"
+        assert doc2.page_strip_mode == "additive", "the class is (re-)stamped"
         page_dir = _pages_dir(tmp_path)
         for n in range(1, 7):
             assert (page_dir / f"{doc2.id}-p{n}.png").is_file(), f"p{n} is missing"
@@ -379,6 +423,7 @@ def test_qualifier_loss_clears_page_count_and_copies(
         doc2 = _doc(db, "pgl", "ikea.pdf")
         assert doc2.id == doc1.id
         assert doc2.page_count is None, "a doc that stopped qualifying loses its strip"
+        assert doc2.page_strip_mode is None, "the class is cleared with the count"
         assert not list(_pages_dir(tmp_path).glob(f"{doc2.id}-p*.png")), (
             "the copies must be deleted on qualifier loss"
         )
@@ -411,6 +456,7 @@ def test_unopenable_pdf_page_render_is_fail_soft(
         assert (summary.files, summary.added, summary.errors) == (1, 1, 0)
         doc = _doc(db, "pgn", "garbage.pdf")
         assert doc.page_count is None, "no pages rendered — no strip"
+        assert doc.page_strip_mode is None, "the class is cleared with the count"
         assert not _pages_dir(tmp_path).exists(), "no copies — the dir is never created"
         assert doc.content == "", "the fallback's all-failed render lands empty content"
         assert summary.summaries == 1, "the document is indexed exactly as pre-phase"
@@ -493,10 +539,11 @@ def test_write_exception_is_fail_soft_and_leaves_no_orphans(
     monkeypatch: pytest.MonkeyPatch,
     caplog: pytest.LogCaptureFixture,
 ) -> None:
-    """The PNG WRITER raises (a full disk) after the FIRST copy
-    landed: the copies this call wrote are removed (no partial
-    orphans), ``page_count`` NULL, the warning is the signal, and the
-    document indexes exactly as pre-phase."""
+    """The PNG WRITER raises (a full disk) after the FIRST atomic copy
+    landed: this call's ``.tmp`` files and the final-name files it
+    CREATED are removed (no partial orphans — phase 163, task 02),
+    ``page_count`` AND ``page_strip_mode`` NULL, the warning is the
+    signal, and the document indexes exactly as pre-phase."""
     root = tmp_path / "pgw"
     root.mkdir()
     _build_ikea_like_pdf(root / "ikea.pdf")
@@ -507,22 +554,29 @@ def test_write_exception_is_fail_soft_and_leaves_no_orphans(
 
     def boom(self: Path, data: bytes) -> int:
         written_paths.append(self)
+        n = original_write(self, data)  # the tmp file really lands first
         if len(written_paths) > 1:
             raise OSError("simulated disk full (test sentinel)")
-        return original_write(self, data)
+        return n
 
     monkeypatch.setattr(Path, "write_bytes", boom)  # pyright: ignore[reportArgumentType]
     try:
         with caplog.at_level(logging.WARNING, logger="app.importer"):
             summary = asyncio.run(import_sources([root], llm, session=db))
         assert (summary.files, summary.added, summary.errors) == (1, 1, 0)
-        assert len(written_paths) == 2, "p1 landed, p2's write failed"
+        assert len(written_paths) == 2, "p1's tmp landed + replaced, p2's write failed"
+        assert all(p.name.endswith(".png.tmp") for p in written_paths), (
+            "the writer only ever touches .tmp paths (atomic replace)"
+        )
         doc = _doc(db, "pgw", "ikea.pdf")
         assert doc.page_count is None
+        assert doc.page_strip_mode is None, "the class is cleared with the count"
         assert not list(_pages_dir(tmp_path).glob(f"{doc.id}-p*.png")), (
             "the partial write was cleaned up — no orphans"
         )
-        assert not written_paths[0].exists(), "the landed p1 copy was removed"
+        assert not list(_pages_dir(tmp_path).glob("*.tmp")), (
+            "the failed call's .tmp file was cleaned up too"
+        )
         assert summary.summaries == 1, "the document is indexed exactly as pre-phase"
         assert any("PDF page render failed" in m for m in caplog.messages), (
             caplog.messages
@@ -531,6 +585,246 @@ def test_write_exception_is_fail_soft_and_leaves_no_orphans(
         _cleanup_source(db, "pgw")
 
 
+# ---------------------------------------------------------------------------
+# Phase 163 (task 02) — WRITE-FIRST, atomic per file (LOCKED A4)
+# ---------------------------------------------------------------------------
+
+
+def test_write_first_new_bytes_are_durable_before_any_stale_delete(
+    db, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """THE order pin (LOCKED A4 — the 2026-10-07 live loss): re-rendering
+    a CHANGED (shrunk, 10 → 6) PDF writes every replacement page FIRST
+    (tmp + ``os.replace``) and only then deletes the stale tail — the
+    event log shows ALL replaces of the fresh bytes before the FIRST
+    unlink of an old-extent file, the overwritten pages keep the NEW
+    bytes, the shrunk tail (p7..p10) is gone, and nothing else is
+    deleted."""
+    root = tmp_path / "pgord"
+    root.mkdir()
+    pdf = root / "ikea.pdf"
+    _build_ikea_like_pdf(pdf)
+    llm = _PictorialLLM()
+    llm.settings = _settings(tmp_path)
+    asyncio.run(import_sources([root], llm, session=db))
+    doc1 = _doc(db, "pgord", "ikea.pdf")
+    page_dir = _pages_dir(tmp_path)
+    sentinel = b"OLD-COPY-SENTINEL"
+    for n in range(1, 11):  # make the old copies unmistakably distinguishable
+        (page_dir / f"{doc1.id}-p{n}.png").write_bytes(sentinel)
+
+    events: list[tuple[str, str]] = []
+    real_replace = os.replace
+
+    def replace_spy(src, dst, *args, **kwargs):  # pyright: ignore[reportUnknownParameterType]
+        events.append(("replace", Path(os.fspath(dst)).name))
+        return real_replace(src, dst, *args, **kwargs)
+
+    real_unlink = Path.unlink
+
+    def unlink_spy(self: Path, **kwargs: Any) -> None:
+        if self.parent == page_dir and self.name.startswith(str(doc1.id)):
+            events.append(("unlink", self.name))
+        return real_unlink(self, **kwargs)
+
+    monkeypatch.setattr(importer.os, "replace", replace_spy)
+    monkeypatch.setattr(Path, "unlink", unlink_spy)  # pyright: ignore[reportArgumentType]
+    try:
+        _build_ikea_shrunk(pdf)  # same path, 6 pages — still qualifying
+        s2 = asyncio.run(import_sources([root], llm, session=db))
+        assert (s2.added, s2.updated, s2.unchanged) == (0, 1, 0)
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+        _cleanup_source(db, "pgord")
+    replaces = [name for kind, name in events if kind == "replace"]
+    unlinks = [name for kind, name in events if kind == "unlink"]
+    assert len(replaces) == 6, "the 6 fresh pages are written via os.replace"
+    assert set(unlinks) == {f"{doc1.id}-p{n}.png" for n in range(7, 11)}, (
+        "the stale-tail delete touches ONLY the old extent the render did "
+        "not rewrite — a file about to be overwritten is never deleted"
+    )
+    first_unlink = next(i for i, e in enumerate(events) if e[0] == "unlink")
+    last_replace = max(i for i, e in enumerate(events) if e[0] == "replace")
+    assert last_replace < first_unlink, (
+        f"write-first violated — event order: {events}"
+    )
+    for n in range(1, 7):
+        blob = (page_dir / f"{doc1.id}-p{n}.png").read_bytes()
+        assert blob != sentinel and blob[:8] == PNG_MAGIC, (
+            f"p{n} keeps the NEW rendered bytes"
+        )
+    for n in range(7, 11):
+        assert not (page_dir / f"{doc1.id}-p{n}.png").exists(), f"stale p{n} leaked"
+    assert not list(page_dir.glob("*.tmp")), "no .tmp orphans"
+
+
+def test_mid_write_failure_keeps_the_prior_copies_intact(
+    db,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """THE failure pin (LOCKED A4): the writer raises on the SECOND
+    page's tmp write of a changed re-render — the prior copy set stays
+    on disk INTACT (the rollback-orphan state — the row over zero
+    files — is structurally unrepresentable): every one of the 10 prior
+    files still exists (p1 with the new bytes already atomically
+    replaced before the failure, p2..p10 byte-for-byte the prior
+    copies), zero ``.tmp`` orphans from this call, and the caller's
+    fail-soft fires (``page_count``/``page_strip_mode`` NULL + the
+    warning, the doc indexed fully)."""
+    root = tmp_path / "pgfail"
+    root.mkdir()
+    pdf = root / "ikea.pdf"
+    _build_ikea_like_pdf(pdf)
+    llm = _PictorialLLM()
+    llm.settings = _settings(tmp_path)
+    asyncio.run(import_sources([root], llm, session=db))
+    doc1 = _doc(db, "pgfail", "ikea.pdf")
+    page_dir = _pages_dir(tmp_path)
+    prior = {
+        n: (page_dir / f"{doc1.id}-p{n}.png").read_bytes() for n in range(1, 11)
+    }
+    # Tag the re-render's bytes so the new p1 is recognizable, then
+    # blow up the SECOND tmp write (page 2).
+    _render_spy(
+        monkeypatch,
+        mutate_full=lambda pages: [
+            PNG_MAGIC + f"NEW-{i}".encode() for i in range(len(pages))
+        ],
+    )
+    original_write = Path.write_bytes
+    tmp_writes: list[Path] = []
+
+    def boom(self: Path, data: bytes) -> int:
+        if self.suffix == ".tmp":
+            tmp_writes.append(self)
+            if len(tmp_writes) > 1:
+                raise OSError("simulated disk full (test sentinel)")
+        return original_write(self, data)
+
+    monkeypatch.setattr(Path, "write_bytes", boom)  # pyright: ignore[reportArgumentType]
+    _build_ikea_shrunk(pdf)
+    try:
+        with caplog.at_level(logging.WARNING, logger="app.importer"):
+            s2 = asyncio.run(import_sources([root], llm, session=db))
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+    assert (s2.added, s2.updated, s2.unchanged) == (0, 1, 0)
+    assert len(tmp_writes) == 2, "p1's tmp wrote, p2's tmp write raised"
+    doc2 = _doc(db, "pgfail", "ikea.pdf")
+    assert doc2.page_count is None, "the caller's fail-soft nulled the count"
+    assert doc2.page_strip_mode is None, "the caller's fail-soft nulled the class"
+    assert any("PDF page render failed" in m for m in caplog.messages), caplog.messages
+    # The prior set is INTACT: exactly the 10 names, none lost, none
+    # orphaned on top.
+    assert {p.name for p in page_dir.iterdir()} == {
+        f"{doc1.id}-p{n}.png" for n in range(1, 11)
+    }, "files on disk exactly the prior set"
+    assert (
+        page_dir / f"{doc1.id}-p1.png"
+    ).read_bytes() == PNG_MAGIC + b"NEW-0", (
+        "p1's replacement bytes were durable before the failure (atomic "
+        "replace) and were NOT removed by the cleanup"
+    )
+    for n in range(2, 11):
+        assert (
+            page_dir / f"{doc1.id}-p{n}.png"
+        ).read_bytes() == prior[n], f"prior copy p{n} was disturbed"
+    assert not list(page_dir.glob("*.tmp")), "zero .tmp orphans from this call"
+    assert doc2.chunks, "the document is indexed fully (fail-soft)"
+
+
+def test_page_copies_are_written_atomically_tmp_then_replace(
+    db, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """THE atomic pin (LOCKED A4): the writer NEVER writes a final
+    ``<doc-id>-p{N}.png`` path directly — every page's bytes land on
+    ``<name>.png.tmp`` and ``os.replace`` moves them onto the final
+    name in order (a reader opening the final path never sees truncated
+    bytes), and no ``.tmp`` survives the successful call."""
+    root = tmp_path / "pgatom"
+    root.mkdir()
+    _build_ikea_like_pdf(root / "ikea.pdf")
+    llm = _PictorialLLM()
+    llm.settings = _settings(tmp_path)
+    written: list[Path] = []
+    original_write = Path.write_bytes
+
+    def write_spy(self: Path, data: bytes) -> int:
+        written.append(self)
+        return original_write(self, data)
+
+    replaced: list[tuple[str, str]] = []
+    real_replace = os.replace
+
+    def replace_spy(src, dst, *args, **kwargs):  # pyright: ignore[reportUnknownParameterType]
+        replaced.append((os.fspath(src), os.fspath(dst)))
+        return real_replace(src, dst, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "write_bytes", write_spy)  # pyright: ignore[reportArgumentType]
+    monkeypatch.setattr(importer.os, "replace", replace_spy)
+    try:
+        asyncio.run(import_sources([root], llm, session=db))
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+    doc = _doc(db, "pgatom", "ikea.pdf")
+    page_dir = _pages_dir(tmp_path)
+    assert len(written) == 10 and len(replaced) == 10
+    assert all(p.name.endswith(".png.tmp") for p in written), (
+        "no final path is ever written directly"
+    )
+    for n, (src, dst) in enumerate(replaced, start=1):
+        assert dst == str(page_dir / f"{doc.id}-p{n}.png")
+        assert src == f"{dst}.tmp", "the tmp name is <final>.tmp"
+    assert not list(page_dir.glob("*.tmp")), "no .tmp survives the success path"
+
+
+def test_stale_tail_delete_failure_is_best_effort(
+    db,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """An unreadable STALE-TAIL copy (the write-first tail pass, the
+    ``_delete_page_copies`` convention): the failure is logged, never
+    raised — the sync completes, the row is stamped with the fresh
+    count, and the reachable tail files still go."""
+    root = tmp_path / "pgtail"
+    root.mkdir()
+    pdf = root / "ikea.pdf"
+    _build_ikea_like_pdf(pdf)
+    llm = _PictorialLLM()
+    llm.settings = _settings(tmp_path)
+    asyncio.run(import_sources([root], llm, session=db))
+    doc1 = _doc(db, "pgtail", "ikea.pdf")
+    page_dir = _pages_dir(tmp_path)
+    p10 = page_dir / f"{doc1.id}-p10.png"
+    real_unlink = Path.unlink
+
+    def boom(self: Path, **kwargs: Any) -> None:
+        if self == p10:
+            raise OSError("simulated unreadable file (test sentinel)")
+        return real_unlink(self, **kwargs)
+
+    monkeypatch.setattr(Path, "unlink", boom)  # pyright: ignore[reportArgumentType]
+    _build_ikea_shrunk(pdf)
+    try:
+        with caplog.at_level(logging.WARNING, logger="app.importer"):
+            s2 = asyncio.run(import_sources([root], llm, session=db))
+    finally:
+        monkeypatch.undo()  # pyright: ignore[reportUnknownMemberType]
+    assert (s2.added, s2.updated, s2.unchanged) == (0, 1, 0)
+    doc2 = _doc(db, "pgtail", "ikea.pdf")
+    assert doc2.page_count == 6 and doc2.page_strip_mode == "additive"
+    assert p10.exists(), "the unreadable tail file survived (never raised)"
+    for n in range(7, 10):
+        assert not (page_dir / f"{doc1.id}-p{n}.png").exists(), f"p{n} still leaked"
+    assert any(
+        "could not delete PDF page copy" in m for m in caplog.messages
+    ), caplog.messages
+
+
 # ---------------------------------------------------------------------------
 # The shared cleanup helper (the _delete_image_copy convention)
 # ---------------------------------------------------------------------------

tests/unit/test_summary_edit_ui.py

@@ -117,7 +117,10 @@ def test_gate_runs_after_the_phase36_base_construction() -> None:
     label = js.find('title.textContent = "Summary"')
     text_node = js.find('body.className = "doc-summary-text"')
     append = js.find("section.append(title, body)")
-    mount = js.find("contentEl.appendChild(section)")
+    # Phase 163 (task 04): the mount rides the `slot` variable —
+    # slot === contentEl for every non-additive doc (the byte-identity
+    # property), views only for the additive strip class.
+    mount = js.find("slot.appendChild(section)")
     gate = js.find("void docAdminReady().then(", mount)
     wiring = js.find("if (admin) wireSummaryEdit(section, doc);")
     assert 0 < base < label < text_node < append < mount < gate < wiring, (

tests/unit/test_viewer_additive_toggle.py

@@ -0,0 +1,431 @@
+"""Unit: the additive PDF strip view (phase 163, task 04 — D4, LOCKED A1/A6).
+
+Frontend source-contract pins + node behavioral runs (the
+``test_document_viewer.py`` house pattern) over ``document.js``'s
+``renderDocument`` — the ONE shared core (Sources modal AND
+/document.html):
+
+* the MODE branch — ``page_urls`` + ``page_strip_mode === "additive"``
+  falls through to the text-doc rendering (Summary panel + content,
+  the pre-148 branch reused) wrapped in a ``.doc-views`` container
+  with the ``.doc-view-toggle`` group above it (Text pressed by
+  default, LOCKED A6); ``page_urls`` with the mode ABSENT or
+  ``"primary"`` keeps the phase-148 strip-only branch VERBATIM (append
+  the strip to ``contentEl`` + return — no toggle, no wrapper, no
+  Summary panel); falsy ``page_urls`` is untouched;
+* the toggle semantics — ``role="group"`` + ``aria-label="Document
+  view"``, two ``<button type="button">`` labeled ``Text`` / ``Pages``
+  (fixed strings, no doc-derived text), ``aria-pressed`` true/false
+  initial state, and a click mutating ONLY the two ``aria-pressed``
+  states + the wrapper's ``data-view`` attribute (CSS-driven show/
+  hide — the strip node stays mounted, no re-render, no refetch);
+* the never-build-HTML rule — createElement + properties/textContent
+  only in the new code path (the module's ONE innerHTML stays the
+  escape-first markdown render); the strip imgs keep
+  ``loading = "lazy"`` (the hidden strip never fetches);
+* the ``.doc-view-toggle`` CSS — the house ghost-pill idiom, the
+  pressed state as text + style (never color alone, B5), ≥44px
+  targets, and the ``data-view`` show/hide contract.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
+DOCUMENT_JS = FRONTEND / "assets" / "document.js"
+STYLES_CSS = FRONTEND / "assets" / "styles.css"
+
+HAVE_NODE = shutil.which("node") is not None
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _fn(js: str, name: str) -> str:
+    """The source of a top-level function via balanced-brace counting
+    (the ``test_document_viewer.py`` pattern)."""
+    start = js.find(f"function {name}(")
+    assert start != -1, f"{name}() must exist in document.js"
+    i = js.find("(", start)
+    depth = 0
+    close = i
+    while i < len(js):
+        if js[i] == "(":
+            depth += 1
+        elif js[i] == ")":
+            depth -= 1
+            if depth == 0:
+                close = i
+                break
+        i += 1
+    brace = js.find("{", close)
+    depth = 0
+    for j in range(brace, len(js)):
+        if js[j] == "{":
+            depth += 1
+        elif js[j] == "}":
+            depth -= 1
+            if depth == 0:
+                return js[start : j + 1]
+    raise AssertionError(f"unbalanced braces in {name}()")
+
+
+def _code(js: str) -> str:
+    """The source with comments stripped (the never-build-HTML pins)."""
+    return re.sub(r"//.*?$|/\*.*?\*/", "", js, flags=re.S | re.M)
+
+
+def _run_node(script: str) -> str:
+    proc = subprocess.run(
+        ["node", "-e", script], capture_output=True, text=True, timeout=60
+    )
+    assert proc.returncode == 0, f"node failed: {proc.stderr}"
+    return proc.stdout
+
+
+# ---------------------------------------------------------------------------
+# Source pins — the renderDocument mode branch
+# ---------------------------------------------------------------------------
+
+
+def test_render_document_branches_on_strip_mode() -> None:
+    """The mode branch (LOCKED A2 — the tolerant read): the additive
+    flag keys on the EXACT ``doc.page_strip_mode === "additive"``
+    string (absent / "primary" / anything else ⇒ primary), and the
+    primary/absent strip branch stays the phase-148 shape — append
+    ``docPagesStrip`` to ``contentEl`` and RETURN — evaluated BEFORE
+    any wrapper/toggle construction."""
+    render = _fn(_read(DOCUMENT_JS), "renderDocument")
+    assert 'doc.page_strip_mode === "additive"' in render, (
+        "only the exact additive string switches on the toggle"
+    )
+    gate_i = render.find('const additive = stripEligible && doc.page_strip_mode === "additive";')
+    primary_i = render.find("if (stripEligible && !additive) {")
+    strip_i = render.find("contentEl.appendChild(docPagesStrip(doc, pageUrls));")
+    return_i = render.find("return;", strip_i)
+    wrapper_i = render.find('views.className = "doc-views";')
+    assert -1 < gate_i < primary_i < strip_i < return_i < wrapper_i, (
+        "the primary/absent branch (strip into contentEl + return) precedes "
+        "the additive wrapper — its DOM stays the phase-148 shape verbatim"
+    )
+    # The wrapper + toggle: ONE .doc-views container, the toggle BEFORE
+    # it, both into contentEl; the text view lands in the wrapper.
+    append_i = render.find("contentEl.append(docViewToggle(views), views);")
+    assert wrapper_i < append_i, "the wrapper is built, then appended after its toggle"
+    assert 'views.setAttribute("data-view", "text");' in render, (
+        "LOCKED A6 — Text is the default view"
+    )
+    # The strip mounts ONCE inside the wrapper, after the text view —
+    # never rebuilt on a flip (no docPagesStrip call outside the two
+    # branches).
+    assert render.count("docPagesStrip(doc, pageUrls)") == 2
+    mount_i = render.rfind("views.appendChild(docPagesStrip(doc, pageUrls));")
+    assert mount_i > render.find('slot.appendChild(pre);') or mount_i > render.rfind(
+        "slot.appendChild(wrap);"
+    ), "the strip mounts AFTER the text view inside the wrapper"
+    # The non-additive path is untouched: slot === contentEl (the
+    # pre-148 appends keep their exact shape through the slot var).
+    assert "let slot = contentEl;" in render
+
+
+def test_primary_absent_branch_builds_no_toggle() -> None:
+    """The primary/absent branch is toggle-free by construction: the
+    strip-branch block (from the ``pageUrls`` read to its ``return``)
+    contains NO ``doc-view-toggle`` / ``doc-views`` construction — the
+    strip-only DOM stays byte-identical to pre-phase-163."""
+    render = _fn(_read(DOCUMENT_JS), "renderDocument")
+    primary_start = render.find("if (stripEligible && !additive)")
+    branch = render[render.find("const pageUrls =") : render.find("return;", primary_start)]
+    assert "doc-view-toggle" not in branch
+    assert "doc-views" not in branch
+    assert branch.count("appendChild") == 1, (
+        "the primary branch is exactly the phase-148 append + return"
+    )
+
+
+def test_toggle_never_builds_html_and_labels_are_fixed() -> None:
+    """The never-build-HTML rule: the toggle builders use
+    createElement + properties/textContent only — no innerHTML /
+    outerHTML — and the labels are the FIXED strings ``Text`` /
+    ``Pages`` (no doc-derived text inside the toggle). The module's
+    ONE innerHTML (the escape-first markdown render) survives."""
+    js = _read(DOCUMENT_JS)
+    toggle = _fn(js, "docViewToggle")
+    btn = _fn(js, "viewToggleButton")
+    for body in (toggle, btn):
+        code = _code(body)
+        assert "innerHTML" not in code and "outerHTML" not in code
+    assert 'document.createElement("div")' in toggle
+    assert 'group.setAttribute("role", "group")' in toggle
+    assert 'group.setAttribute("aria-label", "Document view")' in toggle
+    assert 'document.createElement("button")' in btn
+    assert 'btn.type = "button"' in btn
+    assert 'btn.className = "doc-view-btn"' in btn
+    assert 'viewToggleButton("Text")' in toggle
+    assert 'viewToggleButton("Pages")' in toggle
+    # The module-wide XSS contract: exactly one innerHTML, the
+    # renderMarkdown line.
+    whole = _code(js)
+    assert whole.count("innerHTML") == 1
+    assert "outerHTML" not in whole
+
+
+def test_strip_imgs_stay_lazy() -> None:
+    """The phase-148 lazy-img pin re-runs green: the strip builder is
+    UNMODIFIED — every page ``<img>`` keeps ``loading = "lazy"`` (the
+    additive default view never fetches the strip)."""
+    strip = _fn(_read(DOCUMENT_JS), "docPagesStrip")
+    assert 'img.loading = "lazy";' in strip
+
+
+def test_view_toggle_css() -> None:
+    """styles.css: the ``.doc-view-toggle`` group (the chat-column
+    reading width, the pill pair adjacent) + the ``.doc-view-btn``
+    ghost pill (≥44px target, ink-soft text — AA) + the PRESSED state
+    (``[aria-pressed="true"]`` — brand fill + font-weight 700: text +
+    style, never color alone, B5) + the CSS-driven view swap
+    (``.doc-views .doc-pages`` hidden by default; ``[data-view=
+    "pages"]`` hides the Summary panel / .doc-md / .doc-raw /
+    .doc-image and shows the strip as the grid). Provenance comment
+    above the block (house style)."""
+    css = _read(STYLES_CSS)
+    toggle_i = css.find(".doc-view-toggle {")
+    assert toggle_i != -1, "styles.css must style .doc-view-toggle"
+    comment_start = css.rfind("/*", 0, toggle_i)
+    assert -1 < comment_start < toggle_i and "phase 163" in css[comment_start:toggle_i]
+    btn_i = css.find(".doc-view-btn {")
+    pressed_i = css.find('.doc-view-btn[aria-pressed="true"]')
+    assert toggle_i < btn_i < pressed_i
+    btn_rule = css[btn_i : css.find("}", btn_i)]
+    for decl in ("min-height: 44px", "color: var(--ink-soft)", "border: 1px solid var(--line)"):
+        assert decl in btn_rule
+    pressed_rule = css[pressed_i : css.find("}", pressed_i)]
+    assert "background: var(--brand)" in pressed_rule
+    assert "font-weight: 700" in pressed_rule, (
+        "the pressed state is text weight + fill — never color alone (B5)"
+    )
+    # The CSS-driven swap: hidden strip by default; pages hides the
+    # text view and shows the strip.
+    assert '.doc-views .doc-pages { display: none; }' in css
+    for sel in (".doc-summary", ".doc-md", ".doc-raw", ".doc-image"):
+        assert f'.doc-views[data-view="pages"] {sel}' in css
+    assert '.doc-views[data-view="pages"] .doc-pages { display: grid; }' in css
+
+
+# ---------------------------------------------------------------------------
+# Node behavioral runs — the real renderDocument over a minimal fake DOM
+# ---------------------------------------------------------------------------
+
+_FAKE_DOM = """
+function makeEl(tag) {
+  return {
+    tag, className: "", textContent: "", attrs: {}, children: [], handlers: {},
+    setAttribute(k, v) { this.attrs[k] = String(v); },
+    getAttribute(k) { return k in this.attrs ? this.attrs[k] : null; },
+    appendChild(c) { this.children.push(c); return c; },
+    append(...cs) { this.children.push(...cs); },
+    replaceChildren(...cs) { this.children = cs; },
+    addEventListener(ev, fn) { this.handlers[ev] = fn; },
+    click() { this.handlers.click(); },
+  };
+}
+globalThis.document = { createElement: (t) => makeEl(t) };
+function fmtDate(x) { return "DATE:" + x; }
+function metaBadge(cls, text, title) {
+  const s = makeEl("span");
+  s.className = cls;
+  s.textContent = text;
+  if (title !== undefined) s.setAttribute("title", title);
+  return s;
+}
+function copyPathButton() { return makeEl("button"); }
+function originAnchor() { return makeEl("a"); }
+async function docAdminReady() { return false; }
+function wireDateEdit() {}
+function wireSummaryEdit() {}
+function renderMarkdown(s) { return s; }
+function docImageBlock() { return makeEl("div"); }
+function describe(el) {
+  return {
+    tag: el.tag,
+    className: el.className,
+    attrs: el.attrs,
+    text: el.textContent,
+    children: el.children.map(describe),
+  };
+}
+"""
+
+
+def _render_script() -> str:
+    js = _read(DOCUMENT_JS)
+    parts = [
+        _fn(js, n)
+        for n in ("renderDocument", "docViewToggle", "viewToggleButton", "docPagesStrip")
+    ]
+    return _FAKE_DOM + "\n".join(parts)
+
+
+@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
+def test_additive_doc_renders_text_views_and_toggle() -> None:
+    """Behavioral (node, fake DOM): an ADDITIVE doc renders the TEXT
+    doc exactly as a non-qualifying one — Summary panel + content —
+    inside ``.doc-views`` (data-view="text"), with the toggle group
+    FIRST in the content slot: role=group, aria-label="Document
+    view", the two ``doc-view-btn`` buttons labeled Text/Pages, Text
+    aria-pressed="true" (LOCKED A6), and the strip MOUNTED inside the
+    wrapper (figures + lazy imgs) after the text view."""
+    out = _run_node(
+        _render_script()
+        + """
+const doc = {
+  title: "Letumdei", path: "book.pdf", source: "Library", format: "pdf",
+  summary: "A book.", content: "BODY TEXT", created_at: "c", indexed_at: "i",
+  chunks: 9, page_urls: ["/api/documents/x/pages/1", "/api/documents/x/pages/2"],
+  page_strip_mode: "additive",
+};
+const contentEl = makeEl("div");
+renderDocument(doc, { titleEl: makeEl("h1"), metaEl: makeEl("div"), contentEl });
+console.log(JSON.stringify(describe(contentEl)));
+"""
+    )
+    content = json.loads(out)
+    assert [c["className"] for c in content["children"]] == [
+        "doc-view-toggle",
+        "doc-views",
+    ], "the toggle group sits above the .doc-views wrapper"
+    toggle, views = content["children"]
+    assert toggle["attrs"]["role"] == "group"
+    assert toggle["attrs"]["aria-label"] == "Document view"
+    labels = [c["text"] for c in toggle["children"]]
+    assert labels == ["Text", "Pages"]
+    assert [c["attrs"]["aria-pressed"] for c in toggle["children"]] == ["true", "false"], (
+        "Text pressed by default (LOCKED A6)"
+    )
+    for c in toggle["children"]:
+        assert c["tag"] == "button"
+    assert views["attrs"]["data-view"] == "text"
+    assert [c["className"] for c in views["children"]] == [
+        "doc-summary",
+        "doc-raw",
+        "doc-pages",
+    ], "additive = Summary panel + text content + the mounted strip"
+    # pre.textContent — a text node, never parsed as HTML
+    assert views["children"][1]["text"] == "BODY TEXT"
+    strip = views["children"][2]
+    assert len(strip["children"]) == 2, "one figure per page_urls entry"
+
+
+@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
+def test_primary_and_absent_modes_keep_the_strip_only_dom() -> None:
+    """Behavioral: mode "primary" AND an absent mode (the pre-163
+    stamped row — the live Letumdei pre-sync shape) keep the phase-148
+    DOM byte-identically: the content slot holds EXACTLY the
+    ``.doc-pages`` strip — no wrapper, no toggle, no Summary panel,
+    no text block."""
+    out = _run_node(
+        _render_script()
+        + """
+const results = [];
+for (const mode of ["primary", undefined]) {
+  const doc = {
+    title: "Manual", path: "m.pdf", source: "Library", format: "pdf",
+    summary: "A manual.", content: "SHOULD NOT SHOW", created_at: "c",
+    indexed_at: "i", chunks: 4,
+    page_urls: ["/api/documents/y/pages/1"],
+  };
+  if (mode !== undefined) doc.page_strip_mode = mode;
+  const contentEl = makeEl("div");
+  renderDocument(doc, { titleEl: makeEl("h1"), metaEl: makeEl("div"), contentEl });
+  results.push(describe(contentEl));
+}
+console.log(JSON.stringify(results));
+"""
+    )
+    primary, absent = json.loads(out)
+    for content in (primary, absent):
+        assert len(content["children"]) == 1
+        assert content["children"][0]["className"] == "doc-pages"
+        classes = json.dumps(content)
+        assert "doc-view-toggle" not in classes
+        assert "doc-views" not in classes
+        assert "doc-summary" not in classes
+        assert "doc-raw" not in classes, "the strip replaces the text block (primary class)"
+
+
+@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
+def test_text_doc_dom_is_untouched() -> None:
+    """Behavioral: a doc with no page_urls is UNTOUCHED — Summary
+    panel + content appended straight to the content slot, no
+    wrapper, no toggle (the byte-identity property for every
+    non-PDF)."""
+    out = _run_node(
+        _render_script()
+        + """
+const doc = {
+  title: "Note", path: "n.pdf", source: "Library", format: "pdf",
+  summary: "S.", content: "TEXT", created_at: "c", indexed_at: "i", chunks: 1,
+};
+const contentEl = makeEl("div");
+renderDocument(doc, { titleEl: makeEl("h1"), metaEl: makeEl("div"), contentEl });
+console.log(JSON.stringify(describe(contentEl)));
+"""
+    )
+    content = json.loads(out)
+    assert [c["className"] for c in content["children"]] == ["doc-summary", "doc-raw"]
+
+
+@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
+def test_toggle_flips_view_without_rerender_or_refetch() -> None:
+    """Behavioral: the toggle handler mutates ONLY the two
+    aria-pressed states + the wrapper's data-view. Clicking Pages
+    flips data-view to "pages"; clicking back to Text reverses; the
+    strip node STAYS MOUNTED the whole time (same object, no
+    re-append — the flip-flop fetches nothing) and the wrapper's
+    children never change count."""
+    out = _run_node(
+        _render_script()
+        + """
+const doc = {
+  title: "Book", path: "b.pdf", source: "Library", format: "pdf",
+  summary: "S.", content: "TEXT", created_at: "c", indexed_at: "i", chunks: 2,
+  page_urls: ["/api/documents/z/pages/1", "/api/documents/z/pages/2"],
+  page_strip_mode: "additive",
+};
+const contentEl = makeEl("div");
+renderDocument(doc, { titleEl: makeEl("h1"), metaEl: makeEl("div"), contentEl });
+const toggle = contentEl.children[0];
+const views = contentEl.children[1];
+const [textBtn, pagesBtn] = toggle.children;
+const stripBefore = views.children[2];
+const countBefore = views.children.length;
+pagesBtn.click();
+const afterPages = {
+  view: views.getAttribute("data-view"),
+  pressed: toggle.children.map((b) => b.getAttribute("aria-pressed")),
+};
+textBtn.click();
+const afterText = {
+  view: views.getAttribute("data-view"),
+  pressed: toggle.children.map((b) => b.getAttribute("aria-pressed")),
+  stripSame: views.children[2] === stripBefore,
+  countSame: views.children.length === countBefore,
+};
+console.log(JSON.stringify({ afterPages, afterText }));
+"""
+    )
+    res = json.loads(out)
+    assert res["afterPages"] == {"view": "pages", "pressed": ["false", "true"]}
+    assert res["afterText"] == {
+        "view": "text",
+        "pressed": ["true", "false"],
+        "stripSame": True,
+        "countSame": True,
+    }, "the strip node persists across flips — no re-render, no refetch"

tests/unit/test_wide_column_css.py

@@ -13,12 +13,13 @@ without a browser:
 * NO ``@media (min-width: 1500px)`` block anywhere in the file — the
   phase-58 wide-desktop doubling is deleted in full (the token is
   72rem at every viewport);
-* the six reading-column selectors — ``.chat-shell``,
+* the reading-column selectors — ``.chat-shell``,
   ``.shared-shell``, ``.doc-md``, ``.doc-image`` (phase 122, task 04),
-  ``.doc-pages`` (phase 148, task 03 — the page strip), and
-  ``.doc-summary:has(+ .doc-md)`` — each capped with
-  ``max-width: var(--chat-column)`` and NOTHING else in the file uses
-  the token for a max-width (exactly six rules);
+  ``.doc-pages`` (phase 148, task 03 — the page strip),
+  ``.doc-view-toggle`` (phase 163, task 04 — the Text/Pages toggle
+  above the additive views), and ``.doc-summary:has(+ .doc-md)`` —
+  each capped with ``max-width: var(--chat-column)`` and NOTHING else
+  in the file uses the token for a max-width (exactly seven rules);
 * the flipped negative pin — ZERO literal ``max-width: 46rem`` rules
   remain (the phase-27/59/91 form-column caps are retired): the form
   shells (``.tuning-shell``, ``.theme-shell``, ``.doc-edit-shell``)
@@ -121,8 +122,10 @@ def test_the_reading_columns_use_the_token() -> None:
     task 04 — the viewer's image block rides the SAME reading column
     as its .doc-md sibling), .doc-pages (phase 148, task 03 — the
     viewer's page strip rides the SAME reading column in the shared
-    #doc-content slot) and .doc-summary:has(+ .doc-md) each cap with
-    max-width: var(--chat-column) — and exactly those six rules use
+    #doc-content slot), .doc-view-toggle (phase 163, task 04 — the
+    Text/Pages toggle sits above the additive views, aligned with
+    them) and .doc-summary:has(+ .doc-md) each cap with
+    max-width: var(--chat-column) — and exactly those seven rules use
     the token for a max-width (no other selector)."""
     css = _css()
     for selector in (
@@ -131,12 +134,13 @@ def test_the_reading_columns_use_the_token() -> None:
         ".doc-md",
         ".doc-image",
         ".doc-pages",
+        ".doc-view-toggle",
         ".doc-summary:has(+ .doc-md)",
     ):
         assert "max-width: var(--chat-column)" in _rule_block(css, selector), (
             f"{selector} must cap with max-width: var(--chat-column)"
         )
-    assert css.count("max-width: var(--chat-column)") == 6, (
+    assert css.count("max-width: var(--chat-column)") == 7, (
         "exactly the reading-column selectors use the token"
     )