fix(export): address PR #73 review (Literal phase, header guard, tests)

Remove redundant JSONDecodeError branch, tighten phase typing, add
last-resort header byte cap, and add truncation/incremental bookmark tests.

Author: clean6378-max-it

api/export_api.py

@@ -59,7 +59,7 @@ def _read_state() -> ExportStateDict:
         return _load_state_from_disk()
 
 
-def _serialize_export_failures(failures: list[ExportFailure]) -> list[dict[str, str]]:
+def _serialize_export_failures(failures: list[ExportFailure]) -> list[dict[str, object]]:
     return [
         {
             "session_id": item.session_id,
@@ -90,6 +90,8 @@ def _export_warnings_header_payload(
         sample = sample[:-1]
         truncated = True
         payload = {"total_failures": total, "truncated": truncated, "failures": sample}
+    if len(json.dumps(payload, separators=(",", ":"))) > _EXPORT_WARNINGS_HEADER_MAX_BYTES:
+        payload = {"total_failures": total, "truncated": True, "failures": []}
     return payload
 
 

docs/api-reference.md

@@ -389,7 +389,7 @@ When some sessions fail but at least one succeeds, the response is still **`200`
 | 400 | `INVALID_REQUEST_BODY` | Body is not a JSON object | — |
 | 400 | `INVALID_SINCE_MODE` | Invalid `since` value | `since` echoes rejected value |
 | 422 | `EXPORT_NOTHING_TO_EXPORT` | Zero sessions matched (none attempted) | `since` echoes request mode |
-| 422 | `EXPORT_ALL_FAILED` | Candidates existed but every attempted session failed | `since`, `failures` (same shape as `X-Export-Warnings` entries) |
+| 422 | `EXPORT_ALL_FAILED` | Candidates existed but every attempted session failed | `since`, `failures` — flat array of `{"session_id", "code", "message"}` objects (same item shape as the `failures` array inside the `X-Export-Warnings` header) |
 
 ```bash
 curl -X POST -H "Content-Type: application/json" \

tests/test_export_api_bulk.py

@@ -15,7 +15,9 @@
 
 from flask import Flask
 
-from api.export_api import export_bp
+from api.error_codes import ErrorCode
+from api.export_api import _export_warnings_header_payload, export_bp
+from utils.export_engine import ExportFailure
 from utils.jsonl_parser import parse_session
 
 
@@ -124,6 +126,60 @@ def always_fail(path: str):
     assert all(item["message"] == "Failed to parse session" for item in body["failures"])
 
 
+def test_export_warnings_header_payload_truncates_at_entry_limit():
+    failures = [
+        ExportFailure(
+            session_id=f"sess_{i:04d}",
+            message="Failed to parse session",
+            code=ErrorCode.PARSE_ERROR,
+        )
+        for i in range(25)
+    ]
+    payload = _export_warnings_header_payload(failures)
+    assert payload["total_failures"] == 25
+    assert payload["truncated"] is True
+    assert len(payload["failures"]) <= 20
+
+
+def test_export_warnings_header_payload_byte_overflow_fallback(monkeypatch):
+    monkeypatch.setattr("api.export_api._EXPORT_WARNINGS_HEADER_MAX_BYTES", 80)
+    failures = [
+        ExportFailure(
+            session_id="x" * 200,
+            message="Failed to parse session",
+            code=ErrorCode.PARSE_ERROR,
+        )
+    ]
+    payload = _export_warnings_header_payload(failures)
+    assert payload["truncated"] is True
+    assert payload["failures"] == []
+    assert len(json.dumps(payload, separators=(",", ":"))) <= 80
+
+
+def test_bulk_export_partial_fail_incremental_excludes_failed_from_state(
+    client, monkeypatch, export_state_file
+):
+    export_state_file.write_text(
+        json.dumps({"sessions": {}, "exportedCount": 0}),
+        encoding="utf-8",
+    )
+    real_parse = parse_session
+
+    def flaky_parse(path: str):
+        if path.endswith("session_def456.jsonl"):
+            raise json.JSONDecodeError("bad", "doc", 0)
+        return real_parse(path)
+
+    monkeypatch.setattr("utils.export_engine.parse_session", flaky_parse)
+    resp = client.post("/api/export", json={"since": "incremental"})
+    assert resp.status_code == 200
+
+    state = json.loads(export_state_file.read_text(encoding="utf-8"))
+    sessions = state.get("sessions", {})
+    assert "session_abc123" in sessions
+    assert "session_def456" not in sessions
+
+
 def test_bulk_export_partial_fail_excludes_failed_from_state(
     client, monkeypatch, export_state_file
 ):

utils/export_engine.py

@@ -69,12 +69,14 @@ class ExportFailure:
     code: ErrorCode
 
 
-def failure_code_for_exception(exc: Exception, *, phase: str = "parse") -> ErrorCode:
+def failure_code_for_exception(
+    exc: Exception,
+    *,
+    phase: Literal["parse", "export"] = "parse",
+) -> ErrorCode:
     """Map an export exception to a stable :class:`ErrorCode`."""
     if phase == "export":
         return ErrorCode.INTERNAL_ERROR
-    if isinstance(exc, json.JSONDecodeError):
-        return ErrorCode.PARSE_ERROR
     if isinstance(exc, EXPORT_ERRORS):
         return ErrorCode.PARSE_ERROR
     return ErrorCode.INTERNAL_ERROR
@@ -293,7 +295,12 @@ def run_bulk_export(
     result = BulkExportResult()
     manifest: list[dict[str, Any]] = []
 
-    def _record_failure(sid: str, exc: Exception, *, phase: str = "parse") -> None:
+    def _record_failure(
+        sid: str,
+        exc: Exception,
+        *,
+        phase: Literal["parse", "export"] = "parse",
+    ) -> None:
         result.failure_count += 1
         code = failure_code_for_exception(exc, phase=phase)
         result.failures.append(