utils/leetcode_coach/leetcode_coach/review_ledger.py
Krzysztof kuhy Rudnicki 299e3b6fc2 coach: review events, CLI and signed ledger
Add the review and skeleton session-log events, the review_cli write path
(review-list, review-finish, skeleton-open) and the coach's own signed
review ledger. A review event marks the day solved and starts the +3/+10
re-test clock. The flagged report is read through the guard CLI; a guard
failure is could-not-check, never nothing-to-review.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4
2026-11-21 22:05:22 +01:00

140 lines
4.9 KiB
Python

"""The coach's OWN signed ledger: one row per finished review.
``~/.local/share/leetcode-coach/review_ledger.json``, laid out like the
guard's ledger (``{"version": 1, "entries": [...]}``) so ``earned_time``'s
verified-row reader can read it. It is a separate file on purpose: nothing in
the coach may reach the guard's ledger (`relay/__init__.py`).
A row is signed the way every locker signs: HMAC-SHA256 over the canonical
JSON of the row without ``hmac``, keyed with ``/etc/workout-locker/hmac.key``.
`entry_signature` repeats ``earned_time.entry_signature``'s three lines, since
the coach does not depend on ``earned_time``;
``test_earned_time_verifies_the_row_and_signs_it_the_same`` holds the two
together.
Fail closed: without a readable key, or over a ledger file that does not
parse, `record` raises `LedgerError` and writes nothing. Each slug gets one row
ever. The write is a rename over the target, so a crash leaves the old file.
"""
from __future__ import annotations
from datetime import UTC, datetime
import hashlib
import hmac
import json
import logging
import os
from pathlib import Path
import tempfile
from typing import Any, Final
_LOG: Final = logging.getLogger(__name__)
LEDGER_PATH: Final = (
Path.home() / ".local" / "share" / "leetcode-coach" / "review_ledger.json"
)
KEY_FILE: Final = Path("/etc/workout-locker/hmac.key")
VERSION: Final = 1
"""The guard ledger's ``_ledger_io._VERSION``."""
SOURCE: Final = "leetcode-coach-review"
ID_PREFIX: Final = "review:"
class LedgerError(RuntimeError):
"""No signed row could be written; nothing on disk changed."""
def entry_signature(entry: dict[str, object], key: bytes) -> str:
"""The HMAC-SHA256 every locker signs a ledger row with (``hmac`` left out)."""
body = {k: v for k, v in entry.items() if k != "hmac"}
payload = json.dumps(body, sort_keys=True, separators=(",", ":"))
return hmac.new(key, payload.encode(), hashlib.sha256).hexdigest()
def _key() -> bytes:
try:
key = KEY_FILE.read_bytes().strip()
except OSError as exc:
_LOG.warning("cannot read the signing key at %s: %s", KEY_FILE, exc)
msg = f"cannot read the signing key at {KEY_FILE}: {exc}"
raise LedgerError(msg) from exc
if not key:
_LOG.warning("the signing key at %s is empty", KEY_FILE)
msg = f"the signing key at {KEY_FILE} is empty"
raise LedgerError(msg)
return key
def _entries() -> list[Any]:
"""The rows on disk; none while the file does not exist yet."""
if not LEDGER_PATH.exists():
return []
try:
data = json.loads(LEDGER_PATH.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
_LOG.warning("review ledger %s is unreadable: %s", LEDGER_PATH, exc)
msg = f"the review ledger at {LEDGER_PATH} is unreadable, not overwritten"
raise LedgerError(msg) from exc
entries = data.get("entries") if isinstance(data, dict) else None
if not isinstance(entries, list):
_LOG.warning("review ledger %s has no entries list", LEDGER_PATH)
msg = f"the review ledger at {LEDGER_PATH} has no entries, not overwritten"
raise LedgerError(msg)
return entries
def _write(entries: list[Any]) -> None:
text = json.dumps({"version": VERSION, "entries": entries}, indent=2) + "\n"
folder = LEDGER_PATH.parent
try:
folder.mkdir(parents=True, exist_ok=True)
fd, tmp = tempfile.mkstemp(dir=folder, prefix=".review-", suffix=".json")
with os.fdopen(fd, "w", encoding="utf-8") as fh:
fh.write(text)
Path(tmp).replace(LEDGER_PATH)
except OSError as exc:
_LOG.warning("review ledger %s not written: %s", LEDGER_PATH, exc)
msg = f"cannot write the review ledger at {LEDGER_PATH}: {exc}"
raise LedgerError(msg) from exc
def record(slug: str, cause: str, *, now: datetime | None = None) -> bool:
"""Sign and append the row for one finished review.
Args:
slug: The reviewed problem.
cause: The one named cause.
now: The finish time, timezone-aware (default: now, local time).
Returns:
True when the row was written, False when the slug already had one.
Raises:
LedgerError: no key, an unreadable ledger or a failed write; nothing
on disk changed.
"""
key = _key()
entries = _entries()
entry_id = ID_PREFIX + slug
if any(isinstance(e, dict) and e.get("entry_id") == entry_id for e in entries):
return False
moment = now or datetime.now(tz=UTC).astimezone()
row: dict[str, object] = {
"entry_id": entry_id,
"kind": "credit",
"day": moment.date().isoformat(),
"created_at": moment.isoformat(),
"amount": 1,
"device": "pc",
"detail": {
"title_slug": slug,
"cause": cause,
"source": SOURCE,
"finished_at": str(int(moment.timestamp())),
},
}
row["hmac"] = entry_signature(row, key)
_write([*entries, row])
return True