Deepen QA test architecture (#25)

Author: trek-e

CONTEXT.md

@@ -118,6 +118,15 @@ policy, and cache ordering by `last_reused_at`. The code module lives at
 serialize the catalog result.
 _Avoid_: rule list route logic, cached ruling helper, rule history adapter.
 
+**Foundry Import State Ledger**:
+The Pathfinder module behavior behind the `.foundry_chat_import_state.json` file shared by Foundry
+chat import dedupe and Foundry memory projection idempotency: state path naming, missing/malformed
+file tolerance, legacy `imported_keys` compatibility, projection key preservation, and sorted JSON
+write shape. The code module lives at `modules/pathfinder/app/foundry_import_state_ledger.py`.
+Foundry import and projection modules must not duplicate the state-file schema or read-merge-write
+rules.
+_Avoid_: Foundry state helper, chat import JSON cache, projection dedupe file.
+
 **PF Archive Import Plan**:
 The side-effect-free Pathfinder module behavior that turns an on-disk archive root into planned
 Pathfinder Vault writes: markdown walk, known NPC slug discovery, route decisions, large-import
@@ -217,6 +226,7 @@ Adapters should do only translation/auth/delegation.
 - Sweep status store: `app/services/sweep_status_store.py`
 - Background scheduling seam: `app/services/task_runner.py`
 - PF2e Foundry NeDB chat import: `modules/pathfinder/app/foundry_chat_import.py`
+- Foundry Import State Ledger: `modules/pathfinder/app/foundry_import_state_ledger.py`
 - PF2e Rule Query: `modules/pathfinder/app/rule_query.py`
 - Pathfinder Player Interaction: `modules/pathfinder/app/player_interaction_orchestrator.py`
 - Rule Cache Catalog: `modules/pathfinder/app/rule_cache_catalog.py`

interfaces/discord/response_renderer.py

@@ -32,6 +32,8 @@ async def send_rendered_response(send_fn, response: "str | dict") -> None:
         if rtype == "embed":
             await send_fn(content=response.get("content", ""), embed=response["embed"])
             return
+        if rtype == "suppressed":
+            return
         await send_fn(response.get("content", str(response)))
         return
 

interfaces/discord/tests/test_response_renderer.py

@@ -11,10 +11,45 @@ async def test_send_rendered_response_text():
     send_fn.assert_awaited_once_with("hello")
 
 
+async def test_send_rendered_response_empty_text_noops():
+    send_fn = AsyncMock()
+    await response_renderer.send_rendered_response(send_fn, "")
+    send_fn.assert_not_awaited()
+
+
 async def test_send_rendered_response_embed_dict():
     send_fn = AsyncMock()
     embed = object()
     await response_renderer.send_rendered_response(
         send_fn, {"type": "embed", "content": "c", "embed": embed}
     )
     send_fn.assert_awaited_once_with(content="c", embed=embed)
+
+
+async def test_send_rendered_response_file_dict(monkeypatch):
+    class FakeFile:
+        def __init__(self, file_obj, *, filename):
+            self.file_obj = file_obj
+            self.filename = filename
+
+    monkeypatch.setattr(response_renderer.discord, "File", FakeFile, raising=False)
+    send_fn = AsyncMock()
+    await response_renderer.send_rendered_response(
+        send_fn,
+        {
+            "type": "file",
+            "content": "download",
+            "file_bytes": b"abc",
+            "filename": "result.txt",
+        },
+    )
+
+    send_fn.assert_awaited_once()
+    assert send_fn.await_args.kwargs["content"] == "download"
+    assert send_fn.await_args.kwargs["file"].filename == "result.txt"
+
+
+async def test_send_rendered_response_suppressed_dict_noops():
+    send_fn = AsyncMock()
+    await response_renderer.send_rendered_response(send_fn, {"type": "suppressed"})
+    send_fn.assert_not_awaited()

modules/pathfinder/app/foundry_chat_import.py

@@ -6,7 +6,14 @@
 import shutil
 import tempfile
 from pathlib import Path
-from typing import Protocol
+from typing import Any, Callable, Protocol
+
+from app.foundry_import_state_ledger import (
+    load_imported_keys,
+    load_projection_state_dict,
+    save_imported_keys,
+    state_path_for_inbox,
+)
 
 try:
     import plyvel  # type: ignore
@@ -21,7 +28,6 @@ async def put_note(self, path: str, content: str) -> None: ...
 _TAG_RE = re.compile(r"<[^>]+>")
 _WS_RE = re.compile(r"\s+")
 _IMPORTED_SUFFIX_RE = re.compile(r"_imported(?:_\d+)?$")
-_DEDUPE_STATE_FILE = ".foundry_chat_import_state.json"
 
 
 def _strip_html(text: str) -> str:
@@ -182,21 +188,11 @@ def _mark_leveldb_dir_imported(inbox: Path) -> list[str]:
 
 
 def _dedupe_state_path(inbox: Path) -> Path:
-    return inbox / _DEDUPE_STATE_FILE
+    return state_path_for_inbox(inbox)
 
 
 def _load_dedupe_keys(inbox: Path) -> set[str]:
-    path = _dedupe_state_path(inbox)
-    if not path.exists():
-        return set()
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return set()
-    keys = data.get("imported_keys") if isinstance(data, dict) else None
-    if not isinstance(keys, list):
-        return set()
-    return {str(k) for k in keys}
+    return load_imported_keys(inbox)
 
 
 def _load_projection_state(path: Path) -> dict[str, set[str]]:
@@ -214,67 +210,16 @@ def _load_projection_state(path: Path) -> dict[str, set[str]]:
     Pre-Phase-37 state files (only `imported_keys`) load cleanly with empty
     projection sets — no exceptions, no KeyError.
     """
-    out: dict[str, set[str]] = {
-        "imported_keys": set(),
-        "player_projection_keys": set(),
-        "npc_projection_keys": set(),
-    }
-    if not path.exists():
-        return out
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return out
-    if not isinstance(data, dict):
-        return out
-    for key in (
-        "imported_keys",
-        "player_projection_keys",
-        "npc_projection_keys",
-    ):
-        val = data.get(key)
-        if isinstance(val, list):
-            out[key] = {str(k) for k in val}
-    return out
-
-
-def _save_state(
-    path: Path,
-    *,
-    imported_keys: set[str],
-    player_keys: set[str] | None = None,
-    npc_keys: set[str] | None = None,
-) -> None:
-    """Write state file. If projection keys are None, preserve legacy single-array shape.
-
-    When player_keys/npc_keys are provided, all three arrays are emitted. This
-    matches the foundry_memory_projection write shape exactly.
-    """
-    if player_keys is None and npc_keys is None:
-        payload: dict[str, Any] = {"imported_keys": sorted(imported_keys)}
-    else:
-        payload = {
-            "imported_keys": sorted(imported_keys),
-            "player_projection_keys": sorted(player_keys or set()),
-            "npc_projection_keys": sorted(npc_keys or set()),
-        }
-    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return load_projection_state_dict(path)
 
 
 def _save_dedupe_keys(inbox: Path, keys: set[str]) -> None:
-    """Legacy single-array writer — preserved as a thin wrapper over _save_state.
+    """Legacy single-array writer — preserved as a thin wrapper over the ledger.
 
     When projection state is also tracked on disk, the importer must NOT trample
     the projection arrays. Read-then-merge keeps all three buckets intact.
     """
-    path = _dedupe_state_path(inbox)
-    existing = _load_projection_state(path)
-    player = existing["player_projection_keys"]
-    npc = existing["npc_projection_keys"]
-    if player or npc:
-        _save_state(path, imported_keys=keys, player_keys=player, npc_keys=npc)
-    else:
-        _save_state(path, imported_keys=keys)
+    save_imported_keys(inbox, keys)
 
 
 def _message_key(record: dict) -> str:

modules/pathfinder/app/foundry_import_state_ledger.py

@@ -0,0 +1,118 @@
+"""Foundry import/projection state ledger.
+
+Owns the ``.foundry_chat_import_state.json`` file shared by Foundry chat import
+dedupe and Foundry memory projection idempotency. Missing, malformed, and
+legacy one-array files are tolerated so existing inboxes keep importing.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+STATE_FILE_NAME = ".foundry_chat_import_state.json"
+
+
+@dataclass(frozen=True)
+class FoundryImportState:
+    imported_keys: set[str]
+    player_projection_keys: set[str]
+    npc_projection_keys: set[str]
+
+
+def state_path_for_inbox(inbox: Path) -> Path:
+    return inbox / STATE_FILE_NAME
+
+
+def load_foundry_import_state(path: Path) -> FoundryImportState:
+    out = FoundryImportState(
+        imported_keys=set(),
+        player_projection_keys=set(),
+        npc_projection_keys=set(),
+    )
+    if not path.exists():
+        return out
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return out
+    if not isinstance(data, dict):
+        return out
+    return FoundryImportState(
+        imported_keys=_string_set(data.get("imported_keys")),
+        player_projection_keys=_string_set(data.get("player_projection_keys")),
+        npc_projection_keys=_string_set(data.get("npc_projection_keys")),
+    )
+
+
+def load_imported_keys(inbox: Path) -> set[str]:
+    return load_foundry_import_state(state_path_for_inbox(inbox)).imported_keys
+
+
+def load_projection_state_dict(path: Path) -> dict[str, set[str]]:
+    state = load_foundry_import_state(path)
+    return {
+        "imported_keys": state.imported_keys,
+        "player_projection_keys": state.player_projection_keys,
+        "npc_projection_keys": state.npc_projection_keys,
+    }
+
+
+def save_imported_keys(inbox: Path, keys: set[str]) -> None:
+    path = state_path_for_inbox(inbox)
+    existing = load_foundry_import_state(path)
+    if existing.player_projection_keys or existing.npc_projection_keys:
+        _write_state(
+            path,
+            imported_keys=keys,
+            player_keys=existing.player_projection_keys,
+            npc_keys=existing.npc_projection_keys,
+            include_projection_keys=True,
+        )
+        return
+    _write_state(
+        path,
+        imported_keys=keys,
+        player_keys=set(),
+        npc_keys=set(),
+        include_projection_keys=False,
+    )
+
+
+def save_projection_state(
+    path: Path,
+    *,
+    imported_keys: set[str],
+    player_keys: set[str],
+    npc_keys: set[str],
+) -> None:
+    _write_state(
+        path,
+        imported_keys=imported_keys,
+        player_keys=player_keys,
+        npc_keys=npc_keys,
+        include_projection_keys=True,
+    )
+
+
+def _string_set(value: Any) -> set[str]:
+    if not isinstance(value, list):
+        return set()
+    return {str(item) for item in value}
+
+
+def _write_state(
+    path: Path,
+    *,
+    imported_keys: set[str],
+    player_keys: set[str],
+    npc_keys: set[str],
+    include_projection_keys: bool,
+) -> None:
+    payload: dict[str, Any] = {"imported_keys": sorted(imported_keys)}
+    if include_projection_keys:
+        payload["player_projection_keys"] = sorted(player_keys)
+        payload["npc_projection_keys"] = sorted(npc_keys)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")

modules/pathfinder/app/foundry_memory_projection.py

@@ -31,11 +31,15 @@
 """
 from __future__ import annotations
 
-import json
 import logging
 from pathlib import Path
 from typing import Any, Callable
 
+from app.foundry_import_state_ledger import (
+    load_foundry_import_state,
+    load_projection_state_dict,
+    save_projection_state,
+)
 from app.foundry_projection_planner import (
     ProjectionPlan,
     ProjectionState,
@@ -62,28 +66,7 @@ def _load_projection_state(path: Path) -> dict[str, set[str]]:
     Missing file or malformed JSON yields all-empty sets. Tolerant of legacy
     state files that contain only ``imported_keys``.
     """
-    out: dict[str, set[str]] = {
-        "imported_keys": set(),
-        "player_projection_keys": set(),
-        "npc_projection_keys": set(),
-    }
-    if not path.exists():
-        return out
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return out
-    if not isinstance(data, dict):
-        return out
-    for key in (
-        "imported_keys",
-        "player_projection_keys",
-        "npc_projection_keys",
-    ):
-        val = data.get(key)
-        if isinstance(val, list):
-            out[key] = {str(k) for k in val}
-    return out
+    return load_projection_state_dict(path)
 
 
 def _save_projection_state(
@@ -94,12 +77,12 @@ def _save_projection_state(
     npc_keys: set[str],
 ) -> None:
     """Atomically write projection state to disk preserving all three arrays."""
-    payload = {
-        "imported_keys": sorted(imported_keys),
-        "player_projection_keys": sorted(player_keys),
-        "npc_projection_keys": sorted(npc_keys),
-    }
-    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    save_projection_state(
+        path,
+        imported_keys=imported_keys,
+        player_keys=player_keys,
+        npc_keys=npc_keys,
+    )
 
 
 # Success statuses returned by append_npc_history_row that represent a real write.
@@ -192,11 +175,11 @@ async def project_foundry_chat_memory(
       dict with keys: player_updates, npc_updates, player_deduped, npc_deduped,
       unmatched_speakers, dry_run.
     """
-    state = _load_projection_state(dedupe_store_path)
+    state = load_foundry_import_state(dedupe_store_path)
     projection_state = ProjectionState(
-        imported_keys=state["imported_keys"],
-        player_projection_keys=state["player_projection_keys"],
-        npc_projection_keys=state["npc_projection_keys"],
+        imported_keys=state.imported_keys,
+        player_projection_keys=state.player_projection_keys,
+        npc_projection_keys=state.npc_projection_keys,
     )
     plan = await build_foundry_projection_plan(
         records=records,