From 02aaf9b3a23dbf5d0a0c069b56e4095d6e8b28cc Mon Sep 17 00:00:00 2001
From: stumpylog <797416+stumpylog@users.noreply.github.com>
Date: Wed, 29 Jul 2026 14:58:11 -0700
Subject: [PATCH] feat(benchmark): add local JSONL results history log

---
 src/paperless_benchmark/results.py | 39 ++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 src/paperless_benchmark/results.py

diff --git a/src/paperless_benchmark/results.py b/src/paperless_benchmark/results.py
new file mode 100644
index 000000000..d9d54cab0
--- /dev/null
+++ b/src/paperless_benchmark/results.py
@@ -0,0 +1,39 @@
+# src/paperless_benchmark/results.py
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import UTC
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+RESULTS_DIR = Path(__file__).resolve().parent.parent.parent / "benchmark_results"
+
+
+def _current_git_ref() -> str:
+    result = subprocess.run(
+        ["git", "rev-parse", "--short", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip() or "unknown"
+
+
+def append_history(entry: dict[str, Any], *, code_ref: str | None = None) -> None:
+    """
+    Append one line to benchmark_results/history.jsonl -- a local-only,
+    append-only, cross-session record of every `benchmark run`/`profile`
+    invocation. Unlike a single overwritten snapshot file, this survives
+    across sessions so a benchmarking effort picked back up days later has
+    a full timeline instead of only the most recent result.
+    """
+    RESULTS_DIR.mkdir(exist_ok=True)
+    record = {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "code_ref": code_ref or _current_git_ref(),
+        **entry,
+    }
+    with (RESULTS_DIR / "history.jsonl").open("a") as f:
+        f.write(json.dumps(record) + "\n")