codetrail-cli 1.4.1__py3-none-any.whl

codetrail/generate/validate.py

@@ -0,0 +1,218 @@
+"""Validation before a page is saved (design section 6.5).
+
+- A documented block cites a visible file with a line range (at most 40 lines) or a commit, and quotes it; the
+  quote must appear, whitespace-normalized and contiguous, in those lines or in the commit's message. Commit messages
+  are scanned with gitleaks first; a flagged one can't be quoted.
+- Fact links must name existing facts; diagram placeholders must name a known diagram over an existing scope.
+- Checks must have a question and rubric points grounded in existing facts or visible paths.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from codetrail.errors import CodetrailError
+from codetrail.facts import EntityKind, RelationKind
+from codetrail.facts.store import FactStore
+from codetrail.generate.outline import in_scope
+from codetrail.repo.git import run_git
+from codetrail.repo.secrets import SecretScanner
+from codetrail.repo.source import SourceManifest
+
+MARKER = re.compile(r"^>\s*\[!(documented|inferred)\]\s*(\S*)\s*$")
+FACT_LINK = re.compile(r"\[\[([a-z_]+:[^\]\s]+)\]\]")
+DIAGRAM = re.compile(r"^\{\{\s*diagram\b(.*?)\}\}\s*$")
+DIAGRAM_KINDS = {"imports": "scope", "dependencies": "project", "resources": "scope", "system": "focus"}
+FILE_CITATION = re.compile(r"^(?P<path>[^#\s]+)#L(?P<start>\d+)(?:-L(?P<end>\d+))?$")
+COMMIT_CITATION = re.compile(r"^commit:(?P<sha>[0-9a-f]{7,40})$")
+MAX_CITED_LINES = 40
+QUOTE_MARKS = "\"'\u201c\u201d\u2018\u2019\u00ab\u00bb"  # straight and typographic quotation marks
+
+
+@dataclass(frozen=True)
+class RationaleBlock:
+    kind: str
+    citation: str | None
+    text: str
+    line: int
+
+
+@dataclass
+class ValidationContext:
+    source_root: Path
+    manifest: SourceManifest
+    store: FactStore
+    mirror: Path
+    scanner: SecretScanner
+
+
+def parse_rationale(body: str) -> list[RationaleBlock]:
+    blocks = []
+    lines = body.splitlines()
+    index = 0
+    while index < len(lines):
+        marker = MARKER.match(lines[index])
+        if not marker:
+            index += 1
+            continue
+        start = index
+        index += 1
+        content = []
+        while index < len(lines) and lines[index].startswith(">") and not MARKER.match(lines[index]):
+            content.append(lines[index][1:].removeprefix(" "))
+            index += 1
+        blocks.append(RationaleBlock(marker.group(1), marker.group(2) or None, "\n".join(content).strip(), start + 1))
+    return blocks
+
+
+def normalize(text: str) -> str:
+    return " ".join(text.split())
+
+
+FLAGGED_PROBLEM = "The page contains something that looks like a secret"
+
+
+def validate_page(body: str, checks: Sequence[Mapping[str, Any]] | None, context: ValidationContext) -> list[str]:
+    problems: list[str] = []
+    if not body.strip():
+        return ["The page is empty."]
+    # The last check before anything is saved: a page or its checks must hold nothing that looks like a secret.
+    for finding in context.scanner.scan_text(body + "\n" + json.dumps(list(checks or []), ensure_ascii=False)):
+        problems.append(f"{FLAGGED_PROBLEM} ({finding.rule}); leave it out.")
+    if problems:  # the other problems quote the draft, and they reach the retry prompt, the CLI and the page
+        return problems
+    for block in parse_rationale(body):
+        if block.kind == "documented":
+            problems += _check_documented(block, context)
+    for fact in FACT_LINK.findall(body):
+        if context.store.entity(fact) is None:
+            problems.append(f"The fact link [[{fact}]] names no existing fact.")
+    for line in body.splitlines():
+        diagram = DIAGRAM.match(line.strip())
+        if diagram:
+            problems += _check_diagram(diagram.group(1), context)
+    if checks is not None:
+        problems += _check_checks(checks, context)
+    return problems
+
+
+def validate_brief(brief: str, context: ValidationContext, max_words: int) -> list[str]:
+    """A page's brief for coding agents (design 23.3): present, within its words, and valid as a page is. A secret
+    finding keeps its own wording, so a flagged revision is still retried from the page as it stood."""
+    if not brief.strip():
+        return ["The brief is missing."]
+    words = len(brief.split())
+    if words > max_words:
+        return [f"The brief has {words} words; keep it to at most {max_words}."]
+    return [
+        problem if problem.startswith(FLAGGED_PROBLEM) else f"In the brief: {problem}"
+        for problem in validate_page(brief, None, context)
+    ]
+
+
+def _check_documented(block: RationaleBlock, context: ValidationContext) -> list[str]:
+    quote = normalize(block.text).strip(QUOTE_MARKS + " ")
+    where = f"The documented block at line {block.line}"
+    if not quote:
+        return [f"{where} has no quote."]
+    citation = block.citation or ""
+    file = FILE_CITATION.match(citation)
+    commit = COMMIT_CITATION.match(citation)
+    if file:
+        path, start = file.group("path"), int(file.group("start"))
+        end = int(file.group("end") or start)
+        if path not in context.manifest.files:
+            return [f"{where} cites {path}, which isn't a visible file."]
+        if end < start or end - start + 1 > MAX_CITED_LINES:
+            return [f"{where} cites lines {start}-{end}; cite at most {MAX_CITED_LINES} lines, in order."]
+        lines = (context.source_root / PurePosixPath(path)).read_text(encoding="utf-8", errors="replace").splitlines()
+        if start < 1 or end > len(lines):
+            return [f"{where} cites lines {start}-{end}, but {path} has {len(lines)} lines."]
+        if quote not in normalize("\n".join(lines[start - 1 : end])):
+            return [f"{where}: the quote isn't in {path} lines {start}-{end}. Copy the words exactly from those lines."]
+        return []
+    if commit:
+        message = _commit_message(commit.group("sha"), context)
+        if message is None:
+            return [f"{where} cites a commit that doesn't exist in the repository."]
+        if context.scanner.scan_text(message):
+            return [f"{where} cites a commit whose message is withheld (gitleaks flagged it)."]
+        if quote not in normalize(message):
+            return [f"{where}: the quote isn't in the message of commit {commit.group('sha')}."]
+        return []
+    return [f"{where} has no valid citation (use path#L<start>-L<end> or commit:<sha>)."]
+
+
+def _commit_message(sha: str, context: ValidationContext) -> str | None:
+    try:
+        return run_git(["show", "-s", "--format=%B", f"{sha}^{{commit}}"], git_dir=context.mirror).decode(
+            "utf-8", "replace"
+        )
+    except CodetrailError:
+        return None
+
+
+def _check_diagram(arguments: str, context: ValidationContext) -> list[str]:
+    parts = arguments.split()
+    if parts == ["system"]:
+        has_parts = bool(context.store.entities(EntityKind.PART))
+        return [] if has_parts else ["The system diagram would draw nothing: no parts were found."]
+    if len(parts) != 2 or parts[0] not in DIAGRAM_KINDS or "=" not in parts[1]:
+        return [f"The diagram placeholder '{{{{diagram{arguments}}}}}' isn't a known diagram."]
+    kind, (key, value) = parts[0], parts[1].split("=", 1)
+    if key != DIAGRAM_KINDS[kind]:
+        return [f"The {kind} diagram takes {DIAGRAM_KINDS[kind]}=, not {key}=."]
+    if kind in ("imports", "resources") and not any(in_scope(path, [value]) for path in context.manifest.files):
+        return [f"The diagram scope {value} holds no visible file."]
+    if kind == "dependencies":
+        project = context.store.entity(value)
+        if project is None or project.kind is not EntityKind.PROJECT:
+            return [f"The diagram project {value} isn't a project fact."]
+    if not _draws_something(kind, value, context.store):
+        return [f"The {kind} diagram for {value} would draw nothing: no facts of that kind are there."]
+    return []
+
+
+def _draws_something(kind: str, value: str, store: FactStore) -> bool:
+    """Whether the diagram has at least one fact to draw, so no page shows an empty box."""
+    prefix = value.rstrip("/") + "/"
+    if kind == "imports":
+        kinds = (EntityKind.MODULE, EntityKind.SWIFT_TARGET)
+        return any(entity.id.split(":", 1)[1].startswith(prefix) for each in kinds for entity in store.entities(each))
+    if kind == "resources":
+        folders = (entity.id.split(":", 1)[1] + "/" for entity in store.entities(EntityKind.TERRAFORM_MODULE))
+        return any(folder.startswith(prefix) or prefix.startswith(folder) for folder in folders)
+    if kind == "system":
+        focus = value.strip("/")
+        folders = (str(part.attributes.get("folder") or "") for part in store.entities(EntityKind.PART)
+                   if part.attributes.get("kind") != "platform")  # fmt: skip
+        return any(folder == focus or folder.startswith(focus + "/") for folder in folders)
+    return any(relation.source_id == value for relation in store.relations(RelationKind.DEPENDS_ON))
+
+
+def _check_checks(checks: Sequence[Mapping[str, Any]], context: ValidationContext) -> list[str]:
+    if not 1 <= len(checks) <= 6:
+        return ["Write two to four checks."]
+    problems = []
+    for check in checks:
+        name = str(check.get("id", "?"))
+        if not str(check.get("question", "")).strip():
+            problems.append(f"Check {name} has no question.")
+        rubric = check.get("rubric") or []
+        if not rubric:
+            problems.append(f"Check {name} has no rubric.")
+        for point in rubric:
+            for ground in point.get("grounds") or []:
+                ground = str(ground)
+                known_fact = context.store.entity(ground) is not None
+                known_path = any(in_scope(path, [ground]) for path in context.manifest.files)
+                if not (known_fact or known_path):
+                    problems.append(
+                        f"Check {name} is grounded in {ground}, which is neither a fact nor a visible path."
+                    )
+    return problems

codetrail/guide/__init__.py

@@ -0,0 +1,147 @@
+"""The guide: the knowledge base Claude writes, as Markdown with YAML front matter in its own git repository.
+
+It lives in Codetrail's data folder, never in a target. An update writes pages into the working tree and commits once;
+if anything fails, the uncommitted changes are discarded (design section 6.8). Front matter is read with
+`yaml.safe_load`, so no tag in it can build an object.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from codetrail.errors import CodetrailError
+from codetrail.repo.git import run_git
+
+PAGE_ID = re.compile(r"(areas|concepts|paths|digests|answers)/[a-z0-9][a-z0-9-]{0,80}")
+OUTLINE_FILE = "outline.yaml"
+COMMIT_ID = re.compile(r"[0-9a-f]{7,40}")
+# The guide's own commits run no hooks and need no signing key, whatever the user's global git settings say.
+COMMIT_SETTINGS = ["-c", "core.hooksPath=/dev/null", "-c", "commit.gpgsign=false",
+                   "-c", "user.name=Codetrail", "-c", "user.email=codetrail@localhost"]  # fmt: skip
+
+
+@dataclass(frozen=True)
+class Page:
+    id: str
+    meta: dict[str, Any] = field(default_factory=dict)
+    body: str = ""
+
+    @property
+    def kind(self) -> str:
+        return str(self.meta.get("kind", ""))
+
+    @property
+    def title(self) -> str:
+        return str(self.meta.get("title", self.id))
+
+
+def validate_page_id(page_id: str) -> str:
+    if not PAGE_ID.fullmatch(page_id):
+        raise CodetrailError(f"{page_id!r} isn't a valid page id.")
+    return page_id
+
+
+class GuideRepository:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    @property
+    def git_dir(self) -> Path:
+        return self.root / ".git"
+
+    def ensure(self) -> None:
+        if (self.git_dir / "HEAD").exists():
+            return
+        self.root.mkdir(parents=True, exist_ok=True)
+        run_git(["init", "-q", "-b", "main", str(self.root)])
+
+    def _git(self, *arguments: str) -> bytes:
+        return run_git([*COMMIT_SETTINGS, *arguments], git_dir=self.git_dir, work_tree=self.root)
+
+    def path_of(self, page_id: str) -> Path:
+        return self.root / f"{validate_page_id(page_id)}.md"
+
+    def read_page(self, page_id: str) -> Page | None:
+        file = self.path_of(page_id)
+        if not file.exists():
+            return None
+        return parse_page(page_id, file.read_text(encoding="utf-8"))
+
+    def write_page(self, page: Page) -> None:
+        file = self.path_of(page.id)
+        file.parent.mkdir(parents=True, exist_ok=True)
+        file.write_text(render_page(page), encoding="utf-8")
+
+    def pages(self, kind: str | None = None) -> list[Page]:
+        found = []
+        for file in sorted(self.root.glob("*/*.md")):
+            page_id = f"{file.parent.name}/{file.stem}"
+            if PAGE_ID.fullmatch(page_id):
+                page = parse_page(page_id, file.read_text(encoding="utf-8"))
+                if kind is None or page.kind == kind:
+                    found.append(page)
+        return found
+
+    def read_outline(self) -> dict[str, Any] | None:
+        file = self.root / OUTLINE_FILE
+        if not file.exists():
+            return None
+        data = yaml.safe_load(file.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else None
+
+    def write_outline(self, outline: dict[str, Any]) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        text = yaml.safe_dump(outline, sort_keys=False, allow_unicode=True)
+        (self.root / OUTLINE_FILE).write_text(text, encoding="utf-8")
+
+    def has_uncommitted_changes(self) -> bool:
+        # No optional locks: the page checks this while an update may be committing (design 16.3).
+        return bool(self._git("--no-optional-locks", "status", "--porcelain", "--untracked-files=all").strip())
+
+    def head(self) -> str | None:
+        try:
+            return self._git("rev-parse", "--verify", "-q", "HEAD").decode().strip() or None
+        except CodetrailError:
+            return None
+
+    def commit(self, message: str) -> str | None:
+        """Commits every change and returns the commit, or None when nothing changed."""
+        self._git("add", "-A")
+        if not self._git("status", "--porcelain").strip():
+            return None
+        self._git("commit", "-q", "-m", message)
+        return self.head()
+
+    def discard(self) -> None:
+        """Throws away every uncommitted change, back to the last commit."""
+        if self.head() is not None:
+            self._git("reset", "-q", "--hard", "HEAD")
+        self._git("clean", "-q", "-f", "-d")
+
+    def file_at(self, commit: str, page_id: str) -> str | None:
+        if not COMMIT_ID.fullmatch(commit):  # only a commit id reaches git, never an option
+            return None
+        try:
+            return self._git("show", f"{commit}:{validate_page_id(page_id)}.md").decode("utf-8", "replace")
+        except CodetrailError:
+            return None
+
+
+def render_page(page: Page) -> str:
+    front = yaml.safe_dump(page.meta, sort_keys=False, allow_unicode=True)
+    return f"---\n{front}---\n\n{page.body.rstrip()}\n"
+
+
+def parse_page(page_id: str, text: str) -> Page:
+    if text.startswith("---\n"):
+        end = text.find("\n---\n", 4)
+        if end != -1:
+            meta = yaml.safe_load(text[4 : end + 1]) or {}
+            body = text[end + 5 :].lstrip("\n").rstrip()
+            return Page(page_id, meta if isinstance(meta, dict) else {}, body)
+    return Page(page_id, {}, text.rstrip())

codetrail/learn/__init__.py

@@ -0,0 +1,143 @@
+"""Learning state: what the reader has read and learned, and what went stale (design section 8.3).
+
+A page's version is a hash of its body and checks. Passing a check records its hash, so when an update rewrites a
+page, checks that didn't change stay passed and only new or changed ones need answering again. A page is learned when
+every current check has a pass; a page learned before whose version changed is stale until it is learned again.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from codetrail.guide import Page
+
+PASS = "pass"  # noqa: S105 - a verdict, not a password
+VERDICTS = ("pass", "partial", "fail")
+
+
+def _hash(value: Any) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def check_hash(check: Mapping[str, Any]) -> str:
+    return _hash({"question": check.get("question"), "rubric": check.get("rubric")})
+
+
+def page_version(page: Page) -> str:
+    return _hash({"body": page.body, "checks": page.meta.get("checks") or []})
+
+
+def page_checks(page: Page) -> list[dict[str, Any]]:
+    return [check for check in page.meta.get("checks") or [] if isinstance(check, dict) and check.get("id")]
+
+
+@dataclass(frozen=True)
+class PageStatus:
+    state: str  # "unread", "read", "learned" or "stale"
+    passed: set[str] = field(default_factory=set)
+    learned_commit: str | None = None
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+class LearningState:
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        self.connection = connection
+
+    def mark_read(self, page: Page) -> None:
+        self.connection.execute(
+            "INSERT INTO page_marks (page_id, read_version, read_at) VALUES (?, ?, ?)"
+            " ON CONFLICT (page_id) DO UPDATE SET read_version = excluded.read_version, read_at = excluded.read_at",
+            (page.id, page_version(page), _now()),
+        )
+
+    def mark_unread(self, page: Page) -> None:
+        """Takes back a read mark; a learned page stays learned, since that came from its checks."""
+        self.connection.execute(
+            "UPDATE page_marks SET read_version = NULL, read_at = NULL WHERE page_id = ?", (page.id,)
+        )
+
+    def record_attempt(
+        self,
+        page: Page,
+        check: Mapping[str, Any],
+        answer: str,
+        verdict: str,
+        feedback: str,
+        language: str,
+        guide_commit: str | None,
+    ) -> PageStatus:
+        """Stores an attempt; a pass is recorded for the check's hash, and a page whose checks all pass is learned."""
+        digest = check_hash(check)
+        self.connection.execute(
+            "INSERT INTO check_attempts (page_id, check_id, check_hash, answer, verdict, feedback, language,"
+            " attempted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (page.id, str(check["id"]), digest, answer, verdict, feedback, language, _now()),
+        )
+        if verdict == PASS:
+            self.connection.execute(
+                "INSERT OR IGNORE INTO check_passes (page_id, check_id, check_hash, passed_at) VALUES (?, ?, ?, ?)",
+                (page.id, str(check["id"]), digest, _now()),
+            )
+        if self._all_passed(page):
+            self.connection.execute(
+                "INSERT INTO page_marks (page_id, learned_version, learned_commit, learned_at) VALUES (?, ?, ?, ?)"
+                " ON CONFLICT (page_id) DO UPDATE SET learned_version = excluded.learned_version,"
+                " learned_commit = excluded.learned_commit, learned_at = excluded.learned_at",
+                (page.id, page_version(page), guide_commit, _now()),
+            )
+        return self.status(page)
+
+    def _passed(self, page: Page) -> set[str]:
+        passes = {
+            (row["check_id"], row["check_hash"])
+            for row in self.connection.execute(
+                "SELECT check_id, check_hash FROM check_passes WHERE page_id = ?", (page.id,)
+            )
+        }
+        return {str(check["id"]) for check in page_checks(page) if (str(check["id"]), check_hash(check)) in passes}
+
+    def _all_passed(self, page: Page) -> bool:
+        checks = page_checks(page)
+        return bool(checks) and self._passed(page) == {str(check["id"]) for check in checks}
+
+    def status(self, page: Page) -> PageStatus:
+        row = self.connection.execute("SELECT * FROM page_marks WHERE page_id = ?", (page.id,)).fetchone()
+        passed = self._passed(page)
+        learned_commit = row["learned_commit"] if row else None
+        if row and row["learned_version"]:
+            if row["learned_version"] == page_version(page) or self._all_passed(page):
+                return PageStatus("learned", passed, learned_commit)
+            return PageStatus("stale", passed, learned_commit)
+        if row and row["read_version"]:
+            return PageStatus("read", passed)
+        return PageStatus("unread", passed)
+
+    def learned_page_ids(self) -> set[str]:
+        return {
+            row["page_id"]
+            for row in self.connection.execute("SELECT page_id FROM page_marks WHERE learned_version IS NOT NULL")
+        }
+
+    def mark_digest_read(self, digest_id: str) -> None:
+        self.connection.execute(
+            "INSERT OR IGNORE INTO digest_reads (digest_id, read_at) VALUES (?, ?)", (digest_id, _now())
+        )
+
+    def unread_digests(self, digest_ids: Iterable[str]) -> list[str]:
+        read = {row["digest_id"] for row in self.connection.execute("SELECT digest_id FROM digest_reads")}
+        return [digest for digest in digest_ids if digest not in read]
+
+    def attempts(self, page_id: str) -> Sequence[sqlite3.Row]:
+        return self.connection.execute(
+            "SELECT check_id, verdict, feedback, attempted_at FROM check_attempts WHERE page_id = ? ORDER BY id",
+            (page_id,),
+        ).fetchall()

codetrail/learn/routes.py

@@ -0,0 +1,139 @@
+"""The page's learning routes: marks and checks (design section 8).
+
+`POST /learn/read` marks a page or a digest read, and `POST /learn/unread` takes a page's read mark back.
+`POST /learn/checks` sends the reader's answer to the assistant's grading (no tools) and records the attempt; the
+response carries the verdict and the feedback, never the rubric. Feedback that holds something gitleaks flags is
+replaced before it is stored or shown (design section 15.5), and the call's usage is recorded. One grading runs at a
+time. Every route sits behind the security middleware.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+
+import anyio
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse, Response
+from pydantic import BaseModel, ConfigDict, Field
+
+from codetrail.assistant import Assistant, AssistantError, GradeRequest
+from codetrail.assistant.usage import UsageLog
+from codetrail.config import Paths, Price, ToolsSettings
+from codetrail.database import connect
+from codetrail.guide import PAGE_ID, GuideRepository, Page
+from codetrail.learn import VERDICTS, LearningState, page_checks
+from codetrail.repo.secrets import SecretScanner
+from codetrail.web.i18n import Language
+
+
+class ReadMark(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    page_id: str = Field(max_length=200)
+
+
+class CheckAnswer(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    page_id: str = Field(max_length=200)
+    check_id: str = Field(max_length=100)
+    answer: str = Field(min_length=1, max_length=20_000)
+
+
+def learning_router(
+    paths: Paths,
+    name: str,
+    assistant_for: Callable[[], Assistant],
+    language_of: Callable[[], Language],
+    max_answer_chars: int,
+    cooldown_seconds: int,
+    tools: ToolsSettings,
+    prices: Mapping[str, Price] | None = None,
+) -> APIRouter:
+    router = APIRouter()
+    data = paths.target_data(name)
+    guide = GuideRepository(data / "guide")
+    grading: dict[str, float | bool] = {"busy": False, "last": -1e18}
+
+    def find_page(page_id: str) -> Page | None:
+        return guide.read_page(page_id) if PAGE_ID.fullmatch(page_id) else None
+
+    @router.post("/learn/read")
+    def mark_read(mark: ReadMark) -> Response:
+        _ = language_of().translations.gettext
+        page = find_page(mark.page_id)
+        if page is None:
+            return JSONResponse({"error": _("That page doesn't exist.")}, 404)
+        connection = connect(data / "codetrail.db")
+        try:
+            learning = LearningState(connection)
+            if page.kind == "digest":
+                learning.mark_digest_read(page.id)
+            else:
+                learning.mark_read(page)
+        finally:
+            connection.close()
+        return Response(status_code=204)
+
+    @router.post("/learn/unread")
+    def mark_unread(mark: ReadMark) -> Response:
+        _ = language_of().translations.gettext
+        page = find_page(mark.page_id)
+        if page is None or page.kind == "digest":
+            return JSONResponse({"error": _("That page doesn't exist.")}, 404)
+        connection = connect(data / "codetrail.db")
+        try:
+            LearningState(connection).mark_unread(page)
+        finally:
+            connection.close()
+        return Response(status_code=204)
+
+    @router.post("/learn/checks")
+    async def answer_check(submitted: CheckAnswer) -> Response:
+        language = language_of()
+        _ = language.translations.gettext
+        page = find_page(submitted.page_id)
+        check = next((item for item in page_checks(page) if item["id"] == submitted.check_id), None) if page else None
+        if page is None or check is None:
+            return JSONResponse({"error": _("That check doesn't exist.")}, 404)
+        if len(submitted.answer) > max_answer_chars:
+            limit = _("Answers are limited to %(count)s characters.") % {"count": max_answer_chars}
+            return JSONResponse({"error": limit}, 413)
+        if grading["busy"]:  # claimed with no await before it, so two gradings can't both start
+            return JSONResponse({"error": _("Another answer is being graded.")}, 429)
+        if time.monotonic() - float(grading["last"]) < cooldown_seconds:
+            return JSONResponse({"error": _("Wait a few seconds before the next answer.")}, 429)
+        grading["busy"], grading["last"] = True, time.monotonic()
+        try:
+            request = GradeRequest(
+                str(check.get("question", "")), list(check.get("rubric") or []), page.title, page.body,
+                submitted.answer, language.code,
+            )  # fmt: skip
+            verdict = await assistant_for().grade(request)
+        except AssistantError as error:
+            return JSONResponse({"error": str(error)}, 502)
+        finally:
+            grading["busy"] = False
+        feedback = verdict.feedback
+        findings = await anyio.to_thread.run_sync(SecretScanner(tools).scan_text, feedback)
+        if findings:
+            withheld = _("The feedback was withheld: it contains something that looks like a secret (%(rule)s).")
+            feedback = withheld % {"rule": findings[0].rule}
+        if verdict.verdict not in VERDICTS:
+            unread = _("The grade couldn't be read, so nothing was recorded; try again.")
+            return JSONResponse({"error": unread}, 502)
+        connection = connect(data / "codetrail.db")
+        try:
+            cost = UsageLog(connection, prices or {}).record("grade", verdict.usage) or verdict.cost_usd
+            status = LearningState(connection).record_attempt(
+                page, check, submitted.answer, verdict.verdict, feedback, language.code, guide.head()
+            )
+        finally:
+            connection.close()
+        usage = verdict.usage
+        used = {
+            "tokens": usage.input_tokens + usage.cached_input_tokens + usage.output_tokens,
+            "cost_usd": round(cost, 4),
+        }
+        return JSONResponse({"verdict": verdict.verdict, "feedback": feedback, "state": status.state, "usage": used})
+
+    return router