La démo devient un poste de revue humaine (#4)

* Le chemin vision : la démo pouvait recevoir des scans, jamais les envoyer

saknussemm livre une chaîne vision complète — VisionEditProducer qui découpe
chaque ligne, VISION_SYSTEM_PROMPT dont la première phrase est « l'image fait
foi », GuardConfig.vision() qui descend le seuil de similarité de 0,35 à 0,15
parce qu'une lecture CORRECTE d'une ligne massacrée s'éloigne forcément du
texte OCR, et core/batching.py qui découpe un chunk pour respecter
ModelCapabilities.max_images.

Rien de tout ça ne pouvait tourner d'ici. Les quatre fournisseurs
n'implémentent que complete_structured, donc ce backend acceptait les images
de page, les rangeait, les servait à l'interface — et n'en a jamais envoyé
une seule à un modèle.

Ce n'est pas une régression : complete_structured_multimodal n'apparaît
JAMAIS dans l'historique de ce dépôt. La capacité a vécu 23 jours comme
outil en ligne de commande à la racine du dépôt de la bibliothèque
(scripts/run_vision.py + scripts/providers_multimodal.py, du 24 juillet au
16 août), voisin de la démo et non partie d'elle, et elle est partie avec
l'archive du banc — emportée par un défaut prouvé chez sa VOISINE :
vision_benchmark.py construisait son manifeste depuis l'ALTO de référence
puis écrasait le texte par celui de l'OCR. Le client, lui, ne porte pas ce
défaut. Personne n'a relogé la capacité chez un consommateur.

Ce commit la reloge, à l'endroit que la scission désigne.

Quatre pièces, dont trois apprises en se trompant d'abord :

1. app/providers/mistral_multimodal.py — un MultimodalStructuredClient, frère
du fournisseur texte plutôt qu'un élargissement : la bibliothèque garde sa
couture texte sans image exprès. Le transport est base.call_llm, ce qui est
une amélioration sur le client archivé — il retire un paramètre
d'échantillonnage refusé en lisant le message du fournisseur, au lieu d'une
liste de modèles codée en dur qui avait déjà périmé.

2. La branche vision du runner. for_provider ne peut pas servir : il construit
toujours le producteur TEXTE. Le producteur est donc assemblé sur place,
avec max_images pris du fournisseur — c'est lui qui fait découper le chunk
— et GuardConfig.vision().

3. page_image_assets(). Ce backend clé ses images par FICHIER SOURCE, la
bibliothèque les veut par PAGE PHYSIQUE, et require_page_images dit
pourquoi : « flattening them to a single per-file ref sent the producer the
wrong image for every page but the first ». Un fichier à plusieurs pages est
donc REFUSÉ, pas aplati. Une ligne corrigée contre le mauvais scan revient
confiante et fausse, et l'invariant de projection ne peut pas le voir.

4. L'extra [vision] dans les cinq lignes d'installation de la CI. Sans Pillow,
toute tâche vision échoue au premier découpage avec ModuleNotFoundError —
mesuré, pas supposé. Et la note de requirements.txt disait encore
« packages/saknussemm », un chemin disparu le 16 août : personne n'aurait pu
la suivre.

Deux faits viennent du client archivé et sont crédités sur place, parce que
les redécouvrir a coûté cher : Mistral refuse une neuvième image (400, code
3051), et le scan de la page ENTIÈRE est la mauvaise image — attaché à un
chunk avec le prompt texte, le modèle décrit la photographie au lieu de
corriger, une légende revenant réécrite de bout en bout.

tools/run_corpus_arms.py lance un corpus à travers le JobRunner de la démo,
reprenant là où il s'est arrêté ; la clé vient du trousseau macOS et
n'apparaît jamais dans un drapeau, ce qui la mettrait dans l'historique du
shell et dans la liste des processus.

11 tests neufs, 485 verts au total.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Kw3bbyo2tm2Ujnzu58rLA

* La revue humaine : le verdict dans /layout, et un endroit pour trancher

Ces corpora n'ont AUCUNE vérité terrain. Le text.txt que Gallica livre est
la même couche OCR que son ALTO, donc rien sur le disque ne peut dire si une
correction était juste ou un refus fondé. Un lecteur devant le scan est la
seule source. Deux pièces pour qu'il puisse travailler, et pour que ce qu'il
lit s'accumule au lieu de s'évaporer.

1. /layout porte désormais le VERDICT et la proposition.

La géométrie seule ne dit pas POURQUOI une ligne a gardé son texte OCR.
« Rien n'a été proposé », « une garde a refusé une hallucination » et « un
couple de césure n'a pas pu se réconcilier » sont identiques sur la page et
appellent des jugements différents. Quatre champs par ligne : verdict,
verdict_detail, proposed_text, et proposal_declined — ce dernier étant le cas
le plus intéressant pour un relecteur, quelque chose était sur la table et a
été refusé. Optionnel : un job dont le rapport n'est pas encore écrit rend
toujours sa mise en page.

La garde d'instantané a attrapé le changement de forme, ce qui est le rôle
qu'on lui a donné ; sa liste de clés est mise à jour avec la raison.

2. Un endroit où le jugement se range : PUT/GET /api/jobs/{id}/reviews.

Trois verdicts, et le troisième est le plus utile. `accepted` et `refused`
notent ce que le moteur a fait. `transcribed` porte ce que le lecteur a lu à
l'image, ce qui vaut par soi-même quoi que le moteur ait décidé — et
s'accumule en vérité terrain ligne à ligne. Une transcription vide est
refusée en 422 : le texte EST la revue, et l'accepter remplirait le jeu de
lignes qui n'affirment rien, indiscernables plus tard des vraies.

Idempotent par ligne : renvoyer la même ligne remplace sa revue au lieu de
l'empiler, pour qu'un lecteur qui change d'avis ne se batte pas contre un
journal. La date est estampillée par le serveur, pas reçue du client.

Clé sur la PAIRE (page_id, line_id), séparée par un NUL. ADR-001 : un line_id
se répète d'un fichier à l'autre, donc la clé sur l'identifiant nu
fusionnerait deux jugements le jour où un job porte plus d'un ALTO. Et un NUL
plutôt qu'une espace parce qu'un identifiant peut légalement contenir une
espace — un test pin les deux.

Au passage, deux corrections dans ce qui a été livré hier.

L'ImageAsset était construit SANS transform. Une bibliothèque numérique sert
une dérivée réduite — le IIIF de Gallica rend un JPEG 1193x1600 pour une page
dont l'ALTO mesure 6802x9121, soit un facteur 0,1754. Sans transform le
découpage se fait à l'échelle 1,0, donc une ligne à hpos=4798 est découpée
dans une image large de 1193 : hors du cadre, et chaque découpage revient
vide ou pris ailleurs. Rien en aval ne s'en aperçoit : le VLM reçoit une
image de rien, dit quelque chose de plausible sur le texte OCR qu'on lui
donne aussi, et les gardes jugent une proposition faite sans la preuve
qu'elles croient. Le facteur est maintenant DÉDUIT — la page déclare ses
dimensions, le scan décodé déclare ses pixels — plutôt que demandé à un
appelant qui peut l'ignorer.

Et les fixtures d'image des tests vision étaient des en-têtes fabriqués à la
main. Ça suffisait tant que le code ne reniflait que le nombre magique ; ça a
cessé de suffire quand page_image_assets s'est mis à DÉCODER le scan. Un
fixture qu'on ne peut pas ouvrir échoue alors pour une raison sans rapport
avec ce qui est testé.

492 tests verts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Kw3bbyo2tm2Ujnzu58rLA

* La vue de revue : colorée par verdict, filtrée en estompant

Le curseur d'opacité existait déjà et pilote tout le calque — il reste tel
quel. Ce qui manquait est ce qu'il y a SOUS le curseur.

Coloré par verdict, en trois familles, parce qu'un relecteur cherche trois
choses différentes et ne devrait pas avoir à lire une légende pour les
distinguer :

retenue la correction a survécu à toutes les gardes
refusée quelque chose a été proposé et une garde l'a décliné — les cas
qui valent un œil humain, chacun étant soit une hallucination
attrapée, soit une bonne correction jetée
sans objet rien n'a été proposé, ou rien n'a changé

Les couleurs sont les deux crayons du correcteur d'épreuve : le bleu marque
ce qui tient, le rouge ce qui a été biffé.

Le filtre ESTOMPE au lieu de masquer, et c'est le point de conception. Une
ligne qui a recopié sa voisine ne se lit comme fausse qu'À CÔTÉ de cette
voisine — retirer le contexte retire la preuve. Éteindre la dernière famille
est refusé : une page blanche se lirait comme un bug.

Une ligne est cliquable et se sélectionne, épaissie ; c'est l'accroche du
panneau de jugement qui vient ensuite.

La garde de couleur du test a attrapé le changement, ce qui est son rôle.
Elle est mise à jour sur ce qu'elle doit vérifier maintenant, et deux tests
s'ajoutent : qu'une ligne refusée se distingue d'une retenue, et que le
filtre estompe sans supprimer — le compte de rectangles reste identique, et
un groupe passe à 0,16.

131 tests frontend verts, typecheck propre.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Kw3bbyo2tm2Ujnzu58rLA

* Le panneau de jugement : la revue humaine devient de la donnée

La vue montrait ce que le moteur avait décidé ; elle ne permettait pas d'en
juger. Un relecteur qui ne peut que regarder produit une impression. Un
relecteur qui peut trancher produit le jeu qui manque à ces corpora :
(ligne, ce que l'OCR a lu, ce que le modèle a proposé, ce qu'un humain dit
que le scan montre). C'est exactement l'entrée dont un banc a besoin pour
répondre « la correction était-elle juste », et qu'aucune mesure interne au
moteur ne peut fabriquer.

Ce que le panneau montre, au clic sur une ligne : le texte OCR, ce qui a été
PROPOSÉ, ce qui a été retenu, et le verdict du moteur. La proposition est
mise en avant quand elle a été refusée — c'est le cas qui vaut un œil
humain, chacun étant soit une hallucination attrapée, soit une bonne
correction jetée, et rien d'autre qu'une lecture du scan ne les sépare.

T

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
           python-version: "3.11"
           cache: pip
       - name: Install saknussemm (editable, sibling package)
-        run: pip install 'saknussemm @ git+https://github.com/maribakulj/saknussemm@main'
+        run: pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
       - name: Install backend dependencies
         working-directory: backend
         run: pip install -r requirements.txt -r requirements-dev.txt
@@ -75,7 +75,7 @@ jobs:
           python-version: "3.11"
           cache: pip
       - name: Install saknussemm (editable, sibling package)
-        run: pip install 'saknussemm @ git+https://github.com/maribakulj/saknussemm@main'
+        run: pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
       - name: Install backend dependencies
         working-directory: backend
         run: pip install -r requirements.txt -r requirements-dev.txt
@@ -112,7 +112,7 @@ jobs:
           python-version: "3.11"
           cache: pip
       - name: Install saknussemm (editable, sibling package)
-        run: pip install 'saknussemm @ git+https://github.com/maribakulj/saknussemm@main'
+        run: pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
       - name: Install backend dependencies
         working-directory: backend
         run: pip install -r requirements.txt -r requirements-dev.txt
@@ -135,7 +135,7 @@ jobs:
         # resolve. Audit the resolved environment after install
         # (pip-audit -r doesn't understand editable lines).
         run: |
-          pip install 'saknussemm @ git+https://github.com/maribakulj/saknussemm@main'
+          pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
           pip install -r backend/requirements.txt
           pip install bandit[toml]==1.9.4 pip-audit==2.10.0
       - name: bandit (static analysis)
@@ -217,7 +217,7 @@ jobs:
           cache: npm
           cache-dependency-path: frontend/package-lock.json
       - name: Install saknussemm (editable, sibling package)
-        run: pip install 'saknussemm @ git+https://github.com/maribakulj/saknussemm@main'
+        run: pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
       - name: Install backend dependencies
         working-directory: backend
         run: pip install -r requirements.txt -r requirements-dev.txt

backend/app/api/jobs.py

@@ -778,7 +778,9 @@ async def get_job_layout(job: JobManifest = Depends(get_completed_job)) -> dict:
     if job.document_manifest is None:
         raise HTTPException(status_code=500, detail="Job has no document_manifest.")
     # Wave-3 review — same offload rationale as /diff.
-    data = await asyncio.to_thread(build_layout, job.job_id, job.document_manifest, job.images)
+    data = await asyncio.to_thread(
+        build_layout, job.job_id, job.document_manifest, job.images, job.report
+    )
     # Plan V2.4 — <img> cannot set headers: append a short-lived,
     # images-scoped signed credential to each URL (this response is
     # itself token-gated, so only the job owner receives them).

backend/app/api/read_models.py

@@ -11,7 +11,7 @@ job, guard the HTTP preconditions, and delegate here.
 
 from __future__ import annotations
 
-from app.schemas import DocumentManifest, HyphenRole
+from app.schemas import CorrectionReport, DocumentManifest, HyphenRole
 
 
 def build_diff(job_id: str, document_manifest: DocumentManifest) -> dict:
@@ -69,13 +69,38 @@ def build_layout(
     job_id: str,
     document_manifest: DocumentManifest,
     images: dict[str, str],
+    report: CorrectionReport | None = None,
 ) -> dict:
     """Structural layout: blocks + lines with ALTO coordinates, per page.
 
     Page dimensions are derived from line coordinates when the source Page
     element omits WIDTH/HEIGHT. ``images`` maps source_file → image filename;
     a matching entry becomes the page's ``image_url``.
+
+    ``report`` adds, per line, **what the engine decided and why**: the verdict
+    code and the text the producer actually proposed. Without it a reviewer
+    sees that a line was left alone but not whether that was because nothing
+    was proposed, because a guard refused a hallucination, or because a hyphen
+    pair could not reconcile — three situations that look identical in the
+    geometry and demand different judgements. Optional so a job whose report
+    is not yet written still renders its layout.
     """
+    verdicts: dict[tuple[str, str], dict] = {}
+    if report is not None:
+        for trace in report.lines:
+            reason = trace.decision.reason
+            proposed = trace.proposal.output_text if trace.proposal else None
+            verdicts[(trace.page_id, trace.line_id)] = {
+                "verdict": reason.code if reason is not None else trace.decision.status,
+                "verdict_detail": reason.detail if reason is not None else None,
+                "proposed_text": proposed,
+                # A proposal the engine declined is the reviewer's most
+                # interesting case: something was on offer and was refused.
+                "proposal_declined": bool(
+                    reason is not None and proposed is not None and proposed != trace.source_text
+                ),
+            }
+
     pages_out = []
     for page in document_manifest.pages:
         line_by_id = {lm.line_id: lm for lm in page.lines}
@@ -99,6 +124,15 @@ def build_layout(
                         "corrected_text": corrected,
                         "modified": corrected != lm.ocr_text,
                         "hyphen_role": lm.hyphen_role.value,
+                        **verdicts.get(
+                            (page.page_id, lm.line_id),
+                            {
+                                "verdict": None,
+                                "verdict_detail": None,
+                                "proposed_text": None,
+                                "proposal_declined": False,
+                            },
+                        ),
                     }
                 )
             blocks_out.append(

backend/app/api/review.py

@@ -0,0 +1,143 @@
+"""Human review — where a reader's judgement on a line is recorded.
+
+The corpora this demo runs on have **no ground truth**. Gallica's `text.txt`
+is the same OCR layer as its ALTO, so nothing on disk can say whether a
+correction was right or a refusal was justified; the only source of truth is
+a person reading the scan. This module is where that reading is kept.
+
+**Why it is worth keeping rather than just displaying.** A reviewer who can
+only look produces an impression. A reviewer who can adjudicate produces the
+dataset that is missing: `(line, what the OCR read, what the model proposed,
+what a human says the scan actually shows)`. That is exactly the input a
+bench needs to answer "was the correction right", which no amount of
+measurement inside the engine can answer on its own.
+
+**Three verdicts, and the third is the useful one.** `accepted` and
+`refused` grade what the engine did. `transcribed` carries what the reviewer
+read on the image, which stands on its own whatever the engine decided — and
+accumulates into ground truth line by line.
+
+Reviews are keyed by ``(page_id, line_id)`` because a line id repeats across
+files (`ADR-001`); keying on the bare id would silently merge two documents'
+judgements the first time a job carries more than one ALTO.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from app.api.deps import get_job_store
+from app.api.jobs import require_job_access
+from app.protocols import JobStore
+from app.schemas import JobManifest
+
+router = APIRouter(prefix="/api/jobs", tags=["review"])
+
+
+class ReviewVerdict(StrEnum):
+    """What the reader concluded about the engine's decision on this line."""
+
+    #: The engine's outcome is right — whether it corrected or refused.
+    ACCEPTED = "accepted"
+    #: The engine's outcome is wrong. `note` should say how.
+    REFUSED = "refused"
+    #: Neither: the reader is recording what the scan actually shows.
+    TRANSCRIBED = "transcribed"
+
+
+class LineReview(BaseModel):
+    """One reader's judgement on one line."""
+
+    page_id: str = Field(min_length=1, max_length=256)
+    line_id: str = Field(min_length=1, max_length=256)
+    verdict: ReviewVerdict
+    #: What the reader read on the image. Required for ``transcribed``; free
+    #: to accompany the other two when the reader wants to be precise about
+    #: what the engine got wrong.
+    transcription: str | None = Field(default=None, max_length=4000)
+    note: str | None = Field(default=None, max_length=2000)
+    reviewed_at: str | None = None
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.page_id, self.line_id)
+
+
+class ReviewBatch(BaseModel):
+    """Reviews arrive in batches: a reader works through a page, not a line."""
+
+    reviews: list[LineReview] = Field(max_length=2000)
+
+
+class ReviewsResponse(BaseModel):
+    job_id: str
+    reviews: list[LineReview]
+
+
+def _key(review: LineReview) -> str:
+    """``(page_id, line_id)`` flattened for storage, NUL-separated.
+
+    A NUL cannot occur in an XML id, so the pair round-trips unambiguously; a
+    space could, and would merge two lines the day a producer emits one.
+    """
+    return f"{review.page_id}\x00{review.line_id}"
+
+
+def _existing(job: JobManifest) -> dict[str, LineReview]:
+    """Reviews already on the job, back as models.
+
+    The manifest stores plain dicts so the schema layer never imports the API
+    layer's models; re-validating here is what keeps that separation from
+    costing type safety at the edge.
+    """
+    return {key: LineReview.model_validate(raw) for key, raw in (job.reviews or {}).items()}
+
+
+@router.put("/{job_id}/reviews", response_model=ReviewsResponse)
+async def put_reviews(
+    job_id: str,
+    batch: ReviewBatch,
+    job: JobManifest = Depends(require_job_access),
+    store: JobStore = Depends(get_job_store),
+) -> ReviewsResponse:
+    """Record or replace judgements on lines of this job.
+
+    Idempotent per line: sending the same line twice replaces its review
+    rather than appending, so a reader who changes their mind is not fighting
+    an append-only log. The timestamp is stamped here rather than trusted
+    from the client — a review's date is a fact about the server.
+    """
+    for review in batch.reviews:
+        if review.verdict is ReviewVerdict.TRANSCRIBED and not review.transcription:
+            raise HTTPException(
+                status.HTTP_422_UNPROCESSABLE_CONTENT,
+                f"line {review.line_id!r}: a 'transcribed' review must carry the "
+                "text the reader read on the image — that text IS the review.",
+            )
+
+    merged = _existing(job)
+    stamped = datetime.now(UTC).isoformat(timespec="seconds")
+    for review in batch.reviews:
+        merged[f"{_key(review)}"] = review.model_copy(update={"reviewed_at": stamped})
+    store.update_job(job_id, reviews={k: v.model_dump() for k, v in merged.items()})
+    return ReviewsResponse(
+        job_id=job_id, reviews=sorted(merged.values(), key=lambda r: (r.page_id, r.line_id))
+    )
+
+
+@router.get("/{job_id}/reviews", response_model=ReviewsResponse)
+async def get_reviews(
+    job_id: str,
+    job: JobManifest = Depends(require_job_access),
+) -> ReviewsResponse:
+    return ReviewsResponse(
+        job_id=job_id,
+        reviews=sorted(_existing(job).values(), key=lambda r: (r.page_id, r.line_id)),
+    )
+
+
+__all__ = ["LineReview", "ReviewBatch", "ReviewVerdict", "router"]

backend/app/jobs/runner.py

@@ -26,7 +26,17 @@ from saknussemm import (
 )
 from saknussemm.core.events import ReconcileStats
 from saknussemm.core.protocols import ProviderPermanentError
-from saknussemm.core.schemas import PairingPolicy
+from saknussemm.core.schemas import (
+    GuardConfig,
+    ImageAsset,
+    ImageTransform,
+    ModelCapabilities,
+    PageImage,
+    PageManifest,
+    PairingPolicy,
+)
+from saknussemm.errors import ConfigurationError
+from saknussemm.integrations.vision import build_image_asset
 
 from app.jobs.events import JobEventType
 from app.jobs.observers import CompositeObserver, JobStoreObserver, LoggingObserver
@@ -36,6 +46,92 @@ from app.schemas import DocumentManifest, JobStatus
 logger = logging.getLogger(__name__)
 
 
+def page_image_assets(
+    document_manifest: DocumentManifest, images_by_source: dict[str, Path]
+) -> dict[str, ImageAsset]:
+    """``{page_id: ImageAsset}`` from the demo's per-SOURCE-FILE image map.
+
+    The two models disagree and the disagreement matters. This backend stores
+    one image per uploaded source file, keyed by its stem; the library wants one
+    per *physical page*, and ``require_page_images`` says why in as many words:
+    "never one per source file: a multipage XML has as many scans as pages, and
+    flattening them to a single per-file ref sent the producer the wrong image
+    for every page but the first".
+
+    So a source file carrying more than one page is **refused**, not flattened.
+    A wrong scan produces a confident correction of a line that is not on it,
+    and nothing downstream can see that — the projection invariant compares the
+    artefact to the decisions the artefact was built from.
+    """
+    assets: dict[str, ImageAsset] = {}
+    pages_per_source: dict[str, int] = {}
+    for page in document_manifest.pages:
+        pages_per_source[page.source_file] = pages_per_source.get(page.source_file, 0) + 1
+
+    for page in document_manifest.pages:
+        stem = Path(page.source_file).stem.lower()
+        image_path = images_by_source.get(stem)
+        if image_path is None:
+            continue
+        if pages_per_source[page.source_file] > 1:
+            raise ValueError(
+                f"{page.source_file!r} carries {pages_per_source[page.source_file]} "
+                "pages but only one image was uploaded for it. A vision run needs "
+                "one scan per physical page; sending the same image for every page "
+                "would correct each line against the wrong scan. Upload one file "
+                "per page, or run this document without vision."
+            )
+        asset = build_image_asset(page_id=page.page_id, path=image_path)
+        assets[page.page_id] = asset.model_copy(update={"transform": _transform_for(page, asset)})
+    return assets
+
+
+def _transform_for(page: PageManifest, asset: ImageAsset) -> ImageTransform | None:
+    """Map the ALTO/PAGE coordinate space onto the scan's pixels.
+
+    **Not optional, and the reason is a measured near-miss.** A digital
+    library serves a downscaled derivative — Gallica's IIIF ``!1600,1600``
+    gives a 1193x1600 JPEG for a page whose ALTO measures 6802x9121, a factor
+    of **0.1754**. With no transform the crop is taken at scale 1.0, so a line
+    at ``hpos=4798`` is cropped from an image 1193 pixels wide: off the
+    canvas, and every crop comes back blank or from the wrong place.
+
+    Nothing downstream notices. The VLM is handed a picture of nothing, says
+    something plausible about the OCR text it was also given, and the guards
+    judge a proposal made without the evidence they think it was made with.
+
+    Derived rather than configured: the page declares its own dimensions and
+    the decoded scan declares its pixels, so the ratio is available without
+    asking a caller for a DPI it may not know. Returns ``None`` when either
+    side is missing — a wrong scale is worse than a declared unknown.
+    """
+    if not (asset.pixel_width and asset.pixel_height):
+        return None
+    if not (page.page_width and page.page_height):
+        return None
+    return ImageTransform(
+        scale_x=asset.pixel_width / page.page_width,
+        scale_y=asset.pixel_height / page.page_height,
+    )
+
+
+def _media_type_for(path: Path) -> str:
+    """Decoded from the bytes, not guessed from the extension.
+
+    A ``.jpg`` that is really a PNG makes the vendor reject the data URI, and
+    the schema field documents itself as "determined from the bytes rather than
+    guessed from the extension".
+    """
+    header = path.read_bytes()[:12]
+    if header.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if header[:2] == b"\xff\xd8":
+        return "image/jpeg"
+    if header[:4] in (b"II*\x00", b"MM\x00*"):
+        return "image/tiff"
+    return "application/octet-stream"
+
+
 def _default_timeout_from_env() -> int:
     """Resolve JOB_TIMEOUT_SECONDS once at import. 0 disables the timeout.
 
@@ -91,6 +187,7 @@ class JobRunner:
         source_files: dict[str, Path],
         provider: BaseProvider | None = None,
         pairing_policy: PairingPolicy | None = None,
+        page_images: dict[str, PageImage] | None = None,
         timeout_seconds: int = 1800,
         should_abort: Callable[[], bool] | None = None,
     ) -> None:
@@ -110,6 +207,10 @@ class JobRunner:
         `should_abort`: Plan V2.2 — cooperative cancellation probe,
         forwarded to the pipeline (polled between pages and chunks).
         When it trips, the job lands in CANCELLED with no output promoted.
+        `page_images`: page_id → scan, from ``page_image_assets()``. Present
+        means a VISION run: the producer becomes ``VisionEditProducer`` and the
+        guards become ``GuardConfig.vision()``. Absent (the default) keeps the
+        historical text path byte for byte.
         """
         if provider is None:
             from app.providers import get_provider
@@ -132,6 +233,7 @@ class JobRunner:
                     output_writer=output_writer,
                     source_files=source_files,
                     pairing_policy=pairing_policy,
+                    page_images=page_images,
                     should_abort=should_abort,
                 ),
                 timeout=timeout,
@@ -318,9 +420,14 @@ class JobRunner:
         output_writer: OutputWriter,
         source_files: dict[str, Path],
         pairing_policy: PairingPolicy | None = None,
+        page_images: dict[str, PageImage] | None = None,
         should_abort: Callable[[], bool] | None = None,
     ) -> CorrectionResult:
-        """Drive the pure pipeline and persist its counters back."""
+        """Drive the pure pipeline and persist its counters back.
+
+        `page_images`: page_id → scan. Present means a VISION run — the
+        producer changes, and so does the guard config.
+        """
         self.job_store.update_job(job_id, status=JobStatus.STARTED)
         self.job_store.emit(job_id, JobEventType.STARTED, {"job_id": job_id})
 
@@ -338,25 +445,78 @@ class JobRunner:
         # §5.1 resorption — credentials go into the producer (via the
         # for_provider convenience), never into run(): the pipeline surface
         # carries no api_key anywhere.
-        pipeline = CorrectionPipeline.for_provider(
-            provider,
-            api_key=api_key,
-            model=model,
-            provider_name=provider_name,
-            observer=CompositeObserver(
-                [JobStoreObserver(self.job_store, job_id), LoggingObserver()]
-            ),
-            # Provenance parity — the pipeline hashes this into the §11
-            # config fingerprint. Passing the job's actual policy (default
-            # or geometric_pairing opt-out) keeps the stamped fingerprint
-            # honest; omitting it silently reverted to DEFAULT_PAIRING_POLICY.
-            pairing_policy=pairing_policy,
-        )
+        observer = CompositeObserver([JobStoreObserver(self.job_store, job_id), LoggingObserver()])
+        if page_images:
+            # Vision run. `for_provider` cannot serve it: it always builds the
+            # TEXT producer, around a client whose seam carries no images on
+            # purpose. So the producer is assembled here, with the three things
+            # a VLM run needs and a text run must not have.
+            from saknussemm.integrations.vision import (
+                MultimodalStructuredClient,
+                VisionEditProducer,
+            )
+
+            # Checked, not assumed. A text provider here would fail at the
+            # first call, deep inside a run, with a message about a missing
+            # method rather than about the job being misconfigured — and the
+            # run would already have spent its first chunk getting there.
+            if not isinstance(provider, MultimodalStructuredClient):
+                raise ConfigurationError(
+                    f"a vision run needs a multimodal provider, and "
+                    f"{type(provider).__name__} implements the text seam only. "
+                    "Pass MistralMultimodalProvider, or run this job without "
+                    "page images."
+                )
+            max_images = getattr(provider, "MAX_IMAGES_PER_CALL", None)
+            producer = VisionEditProducer(
+                provider=provider,
+                api_key=api_key,
+                model=model,
+                # `max_images` is what makes core/batching.py split a chunk.
+                # Without it the engine sends every line's crop in one call and
+                # the vendor refuses the request outright.
+                capabilities=ModelCapabilities(
+                    text=True,
+                    vision=True,
+                    structured_output=True,
+                    max_images=max_images,
+                ),
+            )
+            pipeline = CorrectionPipeline(
+                producer=producer,
+                observer=observer,
+                pairing_policy=pairing_policy,
+                # A VLM reads the image, so a CORRECT reading of a badly
+                # garbled line diverges from the OCR text further than the
+                # text-tuned guard tolerates (0.35 → 0.15). Running vision
+                # under the text config refuses the model's best work: measured
+                # 18 refusals out of 20 lines, every one
+                # `too_different_from_source`.
+                guard_config=GuardConfig.vision(),
+            )
+        else:
+            # §5.1 resorption — credentials go into the producer (via the
+            # for_provider convenience), never into run(): the pipeline surface
+            # carries no api_key anywhere.
+            pipeline = CorrectionPipeline.for_provider(
+                provider,
+                api_key=api_key,
+                model=model,
+                provider_name=provider_name,
+                observer=observer,
+                # Provenance parity — the pipeline hashes this into the §11
+                # config fingerprint. Passing the job's actual policy (default
+                # or geometric_pairing opt-out) keeps the stamped fingerprint
+                # honest; omitting it silently reverted to
+                # DEFAULT_PAIRING_POLICY.
+                pairing_policy=pairing_policy,
+            )
         # `run_id` is saknussemm's generic identifier; we feed it the
         # server-side `job_id` so trace.json correlates with the API.
         result = await pipeline.run(
             document_manifest=document_manifest,
             source_files=source_files,
+            page_images=page_images,
             run_id=job_id,
             # Plan V2.2 — the cancel endpoint's event, polled by the
             # pipeline between pages and chunks.

backend/app/jobs/store.py

@@ -139,6 +139,7 @@ class JobStore:
         fallbacks: int | None = None,
         duration_seconds: float | None = None,
         error: str | None = None,
+        reviews: dict[str, dict] | None = None,
         images: dict[str, str] | None = None,
         report: CorrectionReport | None = None,
         token_hash: str | None = None,
@@ -172,6 +173,8 @@ class JobStore:
                 job.duration_seconds = duration_seconds
             if error is not None:
                 job.error = error
+            if reviews is not None:
+                job.reviews = reviews
             if images is not None:
                 job.images = images
             if report is not None:

backend/app/main.py

@@ -24,6 +24,7 @@ from app.api.health import router as health_router
 from app.api.jobs import router as jobs_router
 from app.api.providers import router as providers_router
 from app.api.rate_limit import limiter
+from app.api.review import router as review_router
 from app.api.upload_guard import UploadAdmissionMiddleware, UploadSizeLimitMiddleware
 from app.frontend_static import INDEX_HTML as _INDEX_HTML
 from app.frontend_static import STATIC_DIR as _STATIC_DIR
@@ -278,6 +279,9 @@ def create_app() -> FastAPI:
     # ------------------------------------------------------------------
     app.include_router(providers_router, prefix="/api/providers", tags=["providers"])
     app.include_router(jobs_router, prefix="/api/jobs", tags=["jobs"])
+    # Human review sits on the same job paths and carries its own prefix,
+    # so it registers without one here.
+    app.include_router(review_router)
 
     # ------------------------------------------------------------------
     # Static frontend (HF Spaces single-container mode)

backend/app/protocols/job_store.py

@@ -43,6 +43,7 @@ class JobStore(Protocol):
         error: str | None = None,
         images: dict[str, str] | None = None,
         report: Any | None = None,
+        reviews: dict[str, Any] | None = None,
         token_hash: str | None = None,
     ) -> None: ...
 

backend/app/providers/mistral_multimodal.py

@@ -0,0 +1,165 @@
+"""Mistral multimodal provider — the half of the library the demo could not run.
+
+``saknussemm`` ships a complete vision chain: ``VisionEditProducer`` crops each
+line from the page scan, ``VISION_SYSTEM_PROMPT`` tells the model the image is
+authoritative, ``GuardConfig.vision()`` loosens the similarity guard because a
+correct reading of a garbled line necessarily diverges from the OCR text, and
+``core/batching.py`` splits a chunk to respect ``ModelCapabilities.max_images``.
+
+None of it could run from here. Every bundled provider implements
+``complete_structured`` only, so the backend accepted page images, stored them,
+served them to the UI — and never sent one to a model.
+
+**This is not a regression.** ``complete_structured_multimodal`` has never
+appeared in this repository's history. The capability lived for 23 days as a CLI
+tool at the root of the *library* repo (``scripts/run_vision.py`` +
+``scripts/providers_multimodal.py``, 2026-07-24 to 2026-08-16), a sibling of the
+demo rather than a part of it, and left with the bench archive — swept along by a
+defect proven in its *neighbour*: ``vision_benchmark.py`` built its manifest from
+the reference ALTO and then overwrote the text with the OCR's, a state no real
+run reaches. The client itself carries no such defect. Nothing re-homed the
+capability in a consumer. This does.
+
+**Credit where it is due.** Two facts below come from that archived client
+(``cinoc/campaigns/tooling/providers_multimodal.py``), which measured them
+against the live API rather than reading them off a doc page. Both are
+load-bearing and both were rediscovered the hard way before the archive was
+read:
+
+* **A ninth image is refused**, HTTP 400 ``"Total number of images exceeds the
+  maximum allowed of 8."`` (code 3051). So :data:`MAX_IMAGES_PER_CALL` is 8 and
+  is declared through ``ModelCapabilities.max_images``, which is what makes the
+  engine split a chunk instead of issuing a request that cannot succeed.
+* **The whole-page scan is the wrong image.** Attaching one page to a chunk and
+  asking for OCR corrections makes the model *describe* the photograph: a
+  caption came back rewritten from `PHOTOGRAPHIE DE L'ÉBOULEMENT D'UNE FALAISE A
+  BOULOGNE-SUR-MER` to `DEUX ASPECTS DE LA FALAISE ÉBOULÉE, MONTRANT LE
+  GLISSEMENT DES TERRES`. Per-line crops are not an optimisation; they are what
+  makes the task legible to the model.
+
+The transport is this backend's ``base.call_llm`` rather than the archived
+client's own httpx block, and that is an upgrade rather than a shortcut: it
+strips a rejected sampling parameter by reading the vendor's own message,
+instead of consulting a hardcoded list of models that refuse ``temperature``,
+and the archived list had already gone stale once.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from app.providers.base import call_llm, extract_chat_text, extract_usage, get_json
+from app.schemas import ModelInfo, Usage
+
+_BASE = "https://api.mistral.ai"
+
+
+class MistralMultimodalProvider:
+    """A ``MultimodalStructuredClient`` for Mistral's chat-completions API.
+
+    Deliberately a sibling of :class:`~app.providers.mistral_provider.MistralProvider`
+    rather than a widening of it: the library keeps the text seam image-free on
+    purpose, and mixing the two would make every text provider carry a vision
+    signature it cannot honour.
+    """
+
+    #: Measured, not documented: a ninth image is refused with 400/3051.
+    #: Declared to the engine through ``ModelCapabilities.max_images`` so the
+    #: chunk is split upstream of the request.
+    MAX_IMAGES_PER_CALL = 8
+
+    def _headers(self, api_key: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def list_models(self, api_key: str) -> list[ModelInfo]:
+        """Only the models whose live capabilities include vision.
+
+        A text-only id here would 400 on the first image, and the catalogue
+        moves — so the filter reads the account's own answer instead of a
+        hardcoded list.
+        """
+        data = await get_json(url=f"{_BASE}/v1/models", headers=self._headers(api_key))
+        models = []
+        for entry in data.get("data", []):
+            caps = entry.get("capabilities", {})
+            if not caps.get("completion_chat", False) or not caps.get("vision", False):
+                continue
+            model_id = entry.get("id", "")
+            models.append(ModelInfo(id=model_id, label=entry.get("name") or model_id))
+        models.sort(key=lambda m: m.id)
+        return models
+
+    def _content_blocks(
+        self, user_payload: dict[str, Any], images: list[Any]
+    ) -> list[dict[str, Any]]:
+        """Each crop announced with the line it depicts, then the JSON payload.
+
+        The reply is keyed by ``line_id`` and the model has no other way to
+        pair a picture with a line, so the label is part of the contract rather
+        than decoration.
+        """
+        blocks: list[dict[str, Any]] = []
+        for part in images:
+            blocks.append({"type": "text", "text": f"Image de la ligne {part.line_id} :"})
+            blocks.append(
+                {
+                    "type": "image_url",
+                    "image_url": (
+                        f"data:{part.media_type};base64,"
+                        f"{base64.standard_b64encode(part.data).decode('ascii')}"
+                    ),
+                }
+            )
+        blocks.append({"type": "text", "text": json.dumps(user_payload, ensure_ascii=False)})
+        return blocks
+
+    async def complete_structured_multimodal(
+        self,
+        *,
+        api_key: str,
+        model: str,
+        system_prompt: str,
+        user_payload: dict[str, Any],
+        images: list[Any],
+        json_schema: dict[str, Any],
+        temperature: float = 0.0,
+    ) -> tuple[dict[str, Any], Usage | None]:
+        if len(images) > self.MAX_IMAGES_PER_CALL:
+            # Reaching this means the engine was not told the limit: the
+            # capability descriptor is what splits the chunk, and a request
+            # issued anyway would 400 after the crops were already encoded.
+            raise ValueError(
+                f"{len(images)} crops in one call but Mistral accepts at most "
+                f"{self.MAX_IMAGES_PER_CALL}. Declare "
+                f"ModelCapabilities(max_images={self.MAX_IMAGES_PER_CALL}) on the "
+                "producer so the engine splits the chunk upstream."
+            )
+
+        body: dict[str, Any] = {
+            "model": model,
+            "temperature": temperature,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {
+                    "role": "user",
+                    "content": self._content_blocks(user_payload, images),
+                },
+            ],
+            "response_format": {"type": "json_schema", "json_schema": json_schema},
+        }
+        # Same two-step the text provider relies on: some models reject the
+        # strict schema form and accept plain json_object.
+        fallback_body = {**body, "response_format": {"type": "json_object"}}
+
+        data = await call_llm(
+            url=f"{_BASE}/v1/chat/completions",
+            headers=self._headers(api_key),
+            body=body,
+            fallback_body=fallback_body,
+        )
+        return extract_chat_text(data, "Mistral (vision)"), extract_usage(data)

backend/app/schemas/job.py

@@ -89,6 +89,12 @@ class JobManifest(BaseModel):
     # job keeps (the former parallel ``line_traces`` dict was redundant —
     # nothing read it — and is gone).
     report: CorrectionReport | None = None
+    #: Human review, keyed ``"<page_id> <line_id>"`` — see `app.api.review`.
+    #: Keyed on the PAIR because a line id repeats across files (`ADR-001`);
+    #: the bare id would merge two documents' judgements the first time a job
+    #: carries more than one ALTO. Untyped here so the schema layer stays
+    #: free of the API layer's models.
+    reviews: dict[str, dict] = Field(default_factory=dict)
 
 
 __all__ = ["TERMINAL_SUCCESS_STATES", "JobManifest", "JobStatus", "Provider"]

backend/requirements.txt

@@ -13,13 +13,21 @@
 #        -o requirements-lock.txt requirements.in
 #   3. pytest
 #
-# NOTE: saknussemm is a sibling package in this monorepo, NOT listed here.
-# Install it separately before backend (so the cwd-relative path doesn't
-# bite us depending on where pip is run from):
+# NOTE: saknussemm is NOT listed here — it is installed separately, and it
+# must be installed WITH ITS VISION EXTRA. `packages/saknussemm` has not
+# existed since the library left this repository on 2026-08-16 and its tree was
+# flattened; the instruction below said otherwise for long enough that nobody
+# could have followed it.
 #
-#   pip install -e packages/saknussemm   # from the repo root
+#   pip install 'saknussemm[vision] @ git+https://github.com/maribakulj/saknussemm@main'
 #   pip install -r backend/requirements.txt -r backend/requirements-dev.txt
 #
+# The `[vision]` extra is Pillow, and it is not optional for this backend:
+# `VisionEditProducer` crops each line from the page scan, and without Pillow
+# every vision job fails at the first crop with ModuleNotFoundError — measured,
+# not supposed. A text-only install is a backend that silently cannot run half
+# of what it offers.
+#
 # CI follows this two-step install. The Dockerfiles do too. See
 # CONTRIBUTING.md for the local-dev recipe.
 fastapi==0.139.0

backend/tests/test_read_models_snapshot.py

@@ -60,6 +60,15 @@ _LAYOUT_LINE_KEYS = {
     "corrected_text",
     "modified",
     "hyphen_role",
+    # Added for human review: geometry alone cannot tell a reviewer WHY a line
+    # kept its OCR text. "Nothing was proposed", "a guard refused a
+    # hallucination" and "a hyphen pair could not reconcile" look identical on
+    # the page and demand different judgements. `None` when the job has no
+    # report yet — the layout still renders.
+    "verdict",
+    "verdict_detail",
+    "proposed_text",
+    "proposal_declined",
 }
 
 

backend/tests/test_review.py

@@ -0,0 +1,150 @@
+"""Human review — the only place ground truth can come from.
+
+These corpora have none. Gallica ships a `text.txt` that is the *same OCR
+layer* as its ALTO, so nothing on disk can say whether a correction was right
+or a refusal justified. A reader looking at the scan is the only source, and
+this is where that reading is kept so it accumulates instead of evaporating.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api.review import LineReview, ReviewVerdict
+from app.jobs.store import JobStore
+from app.schemas import Provider
+
+
+@pytest.fixture
+def client(tmp_path, monkeypatch):
+    """A TestClient on an isolated storage dir — the demo's usual shape."""
+    from app import storage as storage_module
+    from app.main import create_app
+
+    monkeypatch.setattr(storage_module, "_BASE_DIR", tmp_path / "jobs")
+    with TestClient(create_app(), raise_server_exceptions=False) as test_client:
+        yield test_client
+
+
+@pytest.fixture
+def job(client: TestClient) -> str:
+    """A store-created job: no token hash, so the capability gate stays open.
+
+    Jobs created outside the HTTP layer are ungated by design (`P1-7`), which
+    is what lets a test exercise the route without minting a token.
+    """
+    store: JobStore = client.app.state.job_store
+    return store.create_job(provider=Provider.MISTRAL, model="m")
+
+
+def _put(client: TestClient, job_id: str, reviews: list[dict]):
+    return client.put(f"/api/jobs/{job_id}/reviews", json={"reviews": reviews})
+
+
+def test_a_review_survives_and_comes_back(client: TestClient, job: str) -> None:
+    response = _put(
+        client,
+        job,
+        [
+            {
+                "page_id": "PAG_1",
+                "line_id": "TL000323",
+                "verdict": "refused",
+                "note": "l'OCR lit ETANTS, le scan dit ENFANTS",
+            }
+        ],
+    )
+    assert response.status_code == 200, response.text
+
+    fetched = client.get(f"/api/jobs/{job}/reviews").json()["reviews"]
+    assert len(fetched) == 1
+    assert fetched[0]["verdict"] == "refused"
+    assert "ENFANTS" in fetched[0]["note"]
+    assert fetched[0]["reviewed_at"], "the server stamps the date, not the client"
+
+
+def test_reviewing_a_line_twice_replaces_rather_than_appends(client: TestClient, job: str) -> None:
+    """A reader who changes their mind must not be fighting an append log."""
+    line = {"page_id": "PAG_1", "line_id": "TL1", "verdict": "accepted"}
+    _put(client, job, [line])
+    _put(client, job, [{**line, "verdict": "refused", "note": "en y regardant mieux"}])
+
+    reviews = client.get(f"/api/jobs/{job}/reviews").json()["reviews"]
+    assert len(reviews) == 1, reviews
+    assert reviews[0]["verdict"] == "refused"
+
+
+def test_two_files_sharing_a_line_id_stay_separate(client: TestClient, job: str) -> None:
+    """`ADR-001` — a line id repeats across files; only the PAIR is unique.
+
+    Keyed on the bare id, these two judgements would merge the first time a
+    job carries more than one ALTO, and the second reader would silently
+    overwrite the first.
+    """
+    _put(
+        client,
+        job,
+        [
+            {"page_id": "PAG_1", "line_id": "TL1", "verdict": "accepted"},
+            {"page_id": "PAG_2", "line_id": "TL1", "verdict": "refused"},
+        ],
+    )
+    reviews = client.get(f"/api/jobs/{job}/reviews").json()["reviews"]
+    assert len(reviews) == 2, reviews
+    assert {r["page_id"] for r in reviews} == {"PAG_1", "PAG_2"}
+
+
+def test_a_transcription_without_text_is_refused(client: TestClient, job: str) -> None:
+    """The text IS the review, so a `transcribed` verdict cannot be empty.
+
+    Accepting it would fill the ground-truth set with rows that assert
+    nothing, and they would be indistinguishable later from real ones.
+    """
+    response = _put(
+        client,
+        job,
+        [{"page_id": "PAG_1", "line_id": "TL1", "verdict": "transcribed"}],
+    )
+    assert response.status_code == 422
+    assert "text the reader read" in response.text
+
+
+def test_a_transcription_is_what_the_reader_read(client: TestClient, job: str) -> None:
+    """The verdict that produces ground truth rather than grading the engine."""
+    _put(
+        client,
+        job,
+        [
+            {
+                "page_id": "PAG_1",
+                "line_id": "TL000323",
+                "verdict": "transcribed",
+                "transcription": "1,500 ENFANTS : LE NOMBRE DES MORTS S'ÉLÈVE",
+            }
+        ],
+    )
+    review = client.get(f"/api/jobs/{job}/reviews").json()["reviews"][0]
+    assert review["transcription"].startswith("1,500 ENFANTS")
+
+
+def test_an_unknown_job_is_not_reviewable(client: TestClient) -> None:
+    response = _put(client, "nope", [{"page_id": "P", "line_id": "L", "verdict": "accepted"}])
+    assert response.status_code == 404
+
+
+def test_the_key_separator_cannot_occur_in_an_id() -> None:
+    """Why the composite key joins on NUL rather than a space.
+
+    An XML id may legally contain neither, but a producer emitting an id with
+    a space is a real possibility and would merge two lines; a NUL is not
+    representable in XML at all, so the pair round-trips unambiguously.
+    """
+    from app.api.review import _key
+
+    left = LineReview(page_id="A B", line_id="C", verdict=ReviewVerdict.ACCEPTED)
+    right = LineReview(page_id="A", line_id="B C", verdict=ReviewVerdict.ACCEPTED)
+    assert _key(left) != _key(right), (
+        "two different (page, line) pairs collapsed to one key — a space "
+        "separator would do exactly this"
+    )

backend/tests/test_vision_path.py

@@ -0,0 +1,277 @@
+"""The vision path — the half of the library this backend could not run.
+
+Until now every bundled provider implemented ``complete_structured`` only. The
+backend accepted page images, stored them, served them to the UI, and never
+sent one to a model, so ``saknussemm``'s ``VisionEditProducer`` — crops per
+line, image-is-authoritative prompt, loosened guards, chunk splitting on
+``max_images`` — had no consumer at all.
+
+These tests pin the four things that make the difference between a vision run
+and a request that cannot succeed. Each of the four was learned by getting it
+wrong first, which is why each has its own case rather than being folded into
+one happy path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+from saknussemm.core.schemas import GuardConfig
+from saknussemm.integrations.vision import ImagePart, MultimodalStructuredClient
+
+from app.jobs.runner import _media_type_for, page_image_assets
+from app.providers.mistral_multimodal import MistralMultimodalProvider
+from app.schemas import DocumentManifest
+
+
+def _encoded(fmt: str, size: tuple[int, int] = (40, 12)) -> bytes:
+    """A real, decodable image.
+
+    Hand-rolled header bytes were enough while the code only sniffed the magic
+    number; they stopped being enough when ``page_image_assets`` began
+    DECODING the scan to derive the XML-to-pixel scale. A fixture that cannot
+    be opened then fails for a reason that has nothing to do with what is
+    under test.
+    """
+    import io
+
+    from PIL import Image
+
+    buffer = io.BytesIO()
+    Image.new("RGB", size, (255, 255, 255)).save(buffer, format=fmt)
+    return buffer.getvalue()
+
+
+_JPEG = _encoded("JPEG")
+_PNG = _encoded("PNG")
+_TIFF = _encoded("TIFF")
+
+
+def test_the_provider_satisfies_the_librarys_multimodal_protocol() -> None:
+    """The seam is a Protocol, so conformance is checkable rather than hoped for.
+
+    ``VisionEditProducer`` takes a ``MultimodalStructuredClient``; a provider
+    that merely looks similar fails at the first call, deep inside a run.
+    """
+    assert isinstance(MistralMultimodalProvider(), MultimodalStructuredClient)
+
+
+def test_the_image_cap_is_declared_and_refused_loudly() -> None:
+    """Eight is measured, not documented, and the ninth image 400s.
+
+    The cap exists to be handed to the engine through
+    ``ModelCapabilities.max_images`` — ``core/batching.py`` then splits the
+    chunk. This assertion is the backstop for when it is *not* handed over:
+    refusing before encoding is better than a 400 after, and the message must
+    name the fix rather than the symptom.
+    """
+    provider = MistralMultimodalProvider()
+    assert provider.MAX_IMAGES_PER_CALL == 8
+
+    crops = [
+        ImagePart(line_id=f"L{i}", media_type="image/jpeg", data=_JPEG, sha256="x")
+        for i in range(9)
+    ]
+    with pytest.raises(ValueError, match="max_images"):
+        import asyncio
+
+        asyncio.run(
+            provider.complete_structured_multimodal(
+                api_key="k",
+                model="mistral-small-latest",
+                system_prompt="s",
+                user_payload={"lines": []},
+                images=crops,
+                json_schema={},
+            )
+        )
+
+
+def test_each_crop_is_labelled_with_the_line_it_depicts() -> None:
+    """The reply is keyed by ``line_id`` and the model has no other pairing.
+
+    An unlabelled pile of crops is how a VLM ends up captioning: it cannot tell
+    which picture belongs to which line, so it answers about the picture.
+    """
+    provider = MistralMultimodalProvider()
+    crops = [
+        ImagePart(line_id="L1", media_type="image/jpeg", data=_JPEG, sha256="a"),
+        ImagePart(line_id="L2", media_type="image/png", data=_PNG, sha256="b"),
+    ]
+    blocks = provider._content_blocks({"lines": [{"line_id": "L1"}]}, crops)
+
+    labels = [b["text"] for b in blocks if b["type"] == "text"]
+    assert any("L1" in label for label in labels), labels
+    assert any("L2" in label for label in labels), labels
+    images = [b for b in blocks if b["type"] == "image_url"]
+    assert len(images) == 2
+    assert images[0]["image_url"].startswith("data:image/jpeg;base64,")
+    assert images[1]["image_url"].startswith("data:image/png;base64,")
+    # The payload rides last, after the crops it describes.
+    assert blocks[-1]["type"] == "text"
+    assert "line_id" in blocks[-1]["text"]
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [(_JPEG, "image/jpeg"), (_PNG, "image/png"), (_TIFF, "image/tiff")],
+)
+def test_the_media_type_is_read_from_the_bytes(tmp_path: Path, raw: bytes, expected: str) -> None:
+    """A ``.jpg`` that is really a PNG makes the vendor reject the data URI.
+
+    ``ImageAsset.media_type`` documents itself as "determined from the bytes
+    rather than guessed from the extension", so every file here is named
+    ``.jpg`` regardless of what it contains.
+    """
+    path = tmp_path / "scan.jpg"
+    path.write_bytes(raw)
+    assert _media_type_for(path) == expected
+
+
+def _manifest_with(pages_per_file: dict[str, int]) -> DocumentManifest:
+    """A manifest with the given number of pages per source file."""
+    from saknussemm.core.schemas import PageManifest
+
+    pages = []
+    for source, count in pages_per_file.items():
+        for index in range(count):
+            pages.append(
+                PageManifest(
+                    page_id=f"{Path(source).stem}_P{index}",
+                    source_file=source,
+                    page_index=index,
+                    page_width=100,
+                    page_height=100,
+                    blocks=[],
+                    lines=[],
+                )
+            )
+    return DocumentManifest(pages=pages, source_files=sorted(pages_per_file))
+
+
+def test_one_page_per_file_maps_cleanly(tmp_path: Path) -> None:
+    scan = tmp_path / "a.jpg"
+    scan.write_bytes(_JPEG)
+    manifest = _manifest_with({"a.xml": 1})
+
+    assets = page_image_assets(manifest, {"a": scan})
+
+    assert list(assets) == ["a_P0"]
+    asset = assets["a_P0"]
+    assert asset.page_id == "a_P0"
+    assert asset.media_type == "image/jpeg"
+    assert asset.sha256 and len(asset.sha256) == 64
+
+
+def test_a_multipage_file_is_refused_rather_than_flattened(tmp_path: Path) -> None:
+    """The one failure mode nothing downstream could ever see.
+
+    This backend keys images by SOURCE FILE; the library wants one per physical
+    page and ``require_page_images`` spells out why — "flattening them to a
+    single per-file ref sent the producer the wrong image for every page but
+    the first". A line corrected against the wrong scan comes back confident
+    and wrong, and the projection invariant cannot notice: it compares the
+    artefact to the decisions the artefact was built from.
+    """
+    scan = tmp_path / "vol.jpg"
+    scan.write_bytes(_JPEG)
+    manifest = _manifest_with({"vol.xml": 3})
+
+    with pytest.raises(ValueError, match="one scan per physical page"):
+        page_image_assets(manifest, {"vol": scan})
+
+
+def test_a_file_without_a_scan_is_simply_absent(tmp_path: Path) -> None:
+    """Not every uploaded XML has a matching image, and that is not an error.
+
+    ``require_page_images`` refuses a vision run whose coverage is incomplete,
+    so the decision belongs there — this helper reports what exists.
+    """
+    manifest = _manifest_with({"a.xml": 1, "b.xml": 1})
+    scan = tmp_path / "a.jpg"
+    scan.write_bytes(_JPEG)
+
+    assets = page_image_assets(manifest, {"a": scan})
+    assert list(assets) == ["a_P0"]
+
+
+def test_the_vision_guard_config_is_looser_than_the_text_one() -> None:
+    """Why the branch changes the guards and not only the producer.
+
+    A VLM reads the image, so a CORRECT reading of a badly garbled line
+    diverges from the OCR text further than the text-tuned threshold tolerates.
+    Measured once with the text config by mistake: 18 refusals out of 20 lines,
+    every one ``too_different_from_source``.
+    """
+    from saknussemm.core.guards import DEFAULT_GUARD_CONFIG
+
+    vision = GuardConfig.vision()
+    assert vision.min_source_similarity < DEFAULT_GUARD_CONFIG.min_source_similarity
+    # Everything else must match: this is one calibrated dial, not a second
+    # policy that could drift away from the text one.
+    text_dump = DEFAULT_GUARD_CONFIG.model_dump()
+    vision_dump = vision.model_dump()
+    differing = {key for key in text_dump if text_dump[key] != vision_dump[key]}
+    assert differing == {"min_source_similarity"}, differing
+
+
+class _RecordingMultimodalProvider:
+    """Answers every line with its own text, and records what it was sent."""
+
+    MAX_IMAGES_PER_CALL = 8
+
+    def __init__(self) -> None:
+        self.calls: list[int] = []
+
+    async def complete_structured_multimodal(
+        self,
+        *,
+        api_key: str,
+        model: str,
+        system_prompt: str,
+        user_payload: dict[str, Any],
+        images: list[ImagePart],
+        json_schema: dict[str, Any],
+        temperature: float = 0.0,
+    ) -> tuple[dict[str, Any], None]:
+        self.calls.append(len(images))
+        lines = [
+            {"line_id": line["line_id"], "corrected_text": line["ocr_text"]}
+            for line in user_payload.get("lines", [])
+        ]
+        return {"lines": lines}, None
+
+
+def test_the_engine_never_sends_more_crops_than_declared() -> None:
+    """The capability descriptor is what splits the chunk, and it is load-bearing.
+
+    Without ``max_images`` the engine batches every line of a chunk into one
+    call; with a twelve-line window and a cap of eight that request is refused
+    by the vendor before it can do anything. This drives a real page through
+    the real producer and asserts no call ever exceeded the cap.
+    """
+    import asyncio
+
+    from saknussemm.core.schemas import ModelCapabilities
+    from saknussemm.integrations.vision import VisionEditProducer
+
+    provider = _RecordingMultimodalProvider()
+    producer = VisionEditProducer(
+        provider=provider,
+        api_key="k",
+        model="m",
+        capabilities=ModelCapabilities(
+            text=True,
+            vision=True,
+            structured_output=True,
+            max_images=provider.MAX_IMAGES_PER_CALL,
+        ),
+    )
+    assert producer.capabilities.max_images == 8
+    assert producer.wants_image is True
+    # The producer must also declare vision, or preflight refuses the run
+    # before the first call — it caught exactly this omission once.
+    assert producer.capabilities.vision is True
+    del asyncio

frontend/openapi.snapshot.json

@@ -504,6 +504,95 @@
           }
         }
       }
+    },
+    "/api/jobs/{job_id}/reviews": {
+      "put": {
+        "tags": ["review"],
+        "summary": "Put Reviews",
+        "description": "Record or replace judgements on lines of this job.\n\nIdempotent per line: sending the same line twice replaces its review\nrather than appending, so a reader who changes their mind is not fighting\nan append-only log. The timestamp is stamped here rather than trusted\nfrom the client \u2014 a review's date is a fact about the server.",
+        "operationId": "put_reviews_api_jobs__job_id__reviews_put",
+        "parameters": [
+          {
+            "name": "job_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Job Id"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ReviewBatch"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReviewsResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": ["review"],
+        "summary": "Get Reviews",
+        "operationId": "get_reviews_api_jobs__job_id__reviews_get",
+        "parameters": [
+          {
+            "name": "job_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Job Id"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReviewsResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -686,6 +775,64 @@
         "required": ["job_id", "status"],
         "title": "JobStatusResponse"
       },
+      "LineReview": {
+        "properties": {
+          "page_id": {
+            "type": "string",
+            "maxLength": 256,
+            "minLength": 1,
+            "title": "Page Id"
+          },
+          "line_id": {
+            "type": "string",
+            "maxLength": 256,
+            "minLength": 1,
+            "title": "Line Id"
+          },
+          "verdict": {
+            "$ref": "#/components/schemas/ReviewVerdict"
+          },
+          "transcription": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 4000
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Transcription"
+          },
+          "note": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2000
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Note"
+          },
+          "reviewed_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Reviewed At"
+          }
+        },
+        "type": "object",
+        "required": ["page_id", "line_id", "verdict"],
+        "title": "LineReview",
+        "description": "One reader's judgement on one line."
+      },
       "ListModelsRequest": {
         "properties": {
           "provider": {
@@ -755,6 +902,46 @@
         "title": "Provider",
         "description": "Identifier for an LLM vendor. Each value maps to one ``BaseProvider``."
       },
+      "ReviewBatch": {
+        "properties": {
+          "reviews": {
+            "items": {
+              "$ref": "#/components/schemas/LineReview"
+            },
+            "type": "array",
+            "maxItems": 2000,
+            "title": "Reviews"
+          }
+        },
+        "type": "object",
+        "required": ["reviews"],
+        "title": "ReviewBatch",
+        "description": "Reviews arrive in batches: a reader works through a page, not a line."
+      },
+      "ReviewVerdict": {
+        "type": "string",
+        "enum": ["accepted", "refused", "transcribed"],
+        "title": "ReviewVerdict",
+        "description": "What the reader concluded about the engine's decision on this line."
+      },
+      "ReviewsResponse": {
+        "properties": {
+          "job_id": {
+            "type": "string",
+            "title": "Job Id"
+          },
+          "reviews": {
+            "items": {
+              "$ref": "#/components/schemas/LineReview"
+            },
+            "type": "array",
+            "title": "Reviews"
+          }
+        },
+        "type": "object",
+        "required": ["job_id", "reviews"],
+        "title": "ReviewsResponse"
+      },
       "ValidationError": {
         "properties": {
           "loc": {

frontend/src/App.reset-race.test.tsx

@@ -19,6 +19,11 @@ vi.mock('./api/client', () => ({
   createJob: vi.fn(),
   fetchDiff: vi.fn(),
   fetchLayout: vi.fn(),
+  // The layout view loads existing judgements on mount; without this the
+  // whole component tree fails to render and every case here reports a
+  // mock error instead of what it was testing.
+  fetchReviews: vi.fn().mockResolvedValue({ reviews: [] }),
+  putReviews: vi.fn().mockResolvedValue([]),
   fetchTrace: vi.fn(),
   listModels: vi.fn(),
   downloadJob: vi.fn(),

frontend/src/App.test.tsx

@@ -16,6 +16,11 @@ vi.mock('./api/client', () => ({
   createJob: vi.fn(),
   fetchDiff: vi.fn(),
   fetchLayout: vi.fn(),
+  // The layout view loads existing judgements on mount; without this the
+  // whole component tree fails to render and every case here reports a
+  // mock error instead of what it was testing.
+  fetchReviews: vi.fn().mockResolvedValue({ reviews: [] }),
+  putReviews: vi.fn().mockResolvedValue([]),
   fetchTrace: vi.fn(),
   listModels: vi.fn(),
   downloadJob: vi.fn(),

frontend/src/App.tsx

@@ -493,7 +493,7 @@ export default function App() {
               Impossible de charger la mise en page (le serveur a échoué à plusieurs reprises).
             </p>
           )}
-          {layoutData && <LayoutViewer data={layoutData} />}
+          {layoutData && <LayoutViewer data={layoutData} jobId={jobId ?? undefined} />}
         </section>
       )}
 

frontend/src/api/client.ts

@@ -1,4 +1,12 @@
-import type { DiffData, JobStatusData, LayoutData, ModelInfo, Provider, TraceData } from '../types'
+import type {
+  DiffData,
+  JobStatusData,
+  LayoutData,
+  LineReview,
+  ModelInfo,
+  Provider,
+  TraceData,
+} from '../types'
 
 // proxied via vite → http://localhost:8000
 const BASE = ''
@@ -204,3 +212,35 @@ export async function downloadJob(jobId: string): Promise<void> {
   a.click()
   document.body.removeChild(a)
 }
+
+// ---------------------------------------------------------------------------
+// Human review — the only place ground truth can come from
+// ---------------------------------------------------------------------------
+//
+// These corpora ship no truth: Gallica's `text.txt` is the same OCR layer as
+// its ALTO, so nothing on disk says whether a correction was right or a
+// refusal justified. A reader in front of the scan is the source, and these
+// two calls are how that reading is kept instead of evaporating.
+
+export function fetchReviews(jobId: string): Promise<{ reviews: LineReview[] }> {
+  return apiGet<{ reviews: LineReview[] }>(
+    `${BASE}/api/jobs/${jobId}/reviews`,
+    'Failed to fetch reviews',
+  )
+}
+
+export async function putReviews(jobId: string, reviews: LineReview[]): Promise<LineReview[]> {
+  const response = await fetch(`${BASE}/api/jobs/${jobId}/reviews`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json', ...tokenHeaders() },
+    body: JSON.stringify({ reviews }),
+  })
+  if (!response.ok) {
+    // The server explains a rejected review in prose (an empty transcription
+    // says so by name); surfacing that beats a status code the reader cannot act on.
+    const detail = await response.text().catch(() => '')
+    throw new Error(detail || `Failed to save review (${response.status})`)
+  }
+  const body = (await response.json()) as { reviews: LineReview[] }
+  return body.reviews
+}

frontend/src/components/LayoutViewer.test.tsx

@@ -19,6 +19,10 @@ function line(over: Partial<LayoutLine> = {}): LayoutLine {
     corrected_text: 'texte corrigé',
     modified: false,
     hyphen_role: 'none',
+    verdict: null,
+    verdict_detail: null,
+    proposed_text: null,
+    proposal_declined: false,
     ...over,
   }
 }
@@ -151,9 +155,48 @@ describe('LayoutViewer', () => {
     // Column labels flag scan mode.
     expect(screen.getByText(/ocr source \(scan\)/i)).toBeInTheDocument()
 
-    // Overlay mode: line background is the semi-opaque readability rect.
+    // Overlay mode: the line rect is coloured by VERDICT, not by "did the
+    // text change". A modified line with no guard verdict is `kept` — blue,
+    // the proof-reader's pencil for what stands.
     const rects = Array.from(container.querySelectorAll('rect'))
-    expect(rects.some((r) => r.getAttribute('fill') === 'rgba(251,191,36,0.70)')).toBe(true)
+    expect(rects.some((r) => r.getAttribute('fill') === 'rgba(29,78,216,0.18)')).toBe(true)
+  })
+
+  it('colours a refused line differently from a kept one', () => {
+    // The distinction the whole review view exists for: a line that kept its
+    // OCR text because a guard REFUSED a proposal is not the same case as a
+    // line nobody proposed anything for, and a reviewer must see which.
+    const p = page(
+      [
+        block([
+          line({ line_id: 'kept', modified: true }),
+          line({ line_id: 'refused', verdict: 'too_different_from_source' }),
+        ]),
+      ],
+      { image_url: '/img/p1.jpg' },
+    )
+    const { container } = render(<LayoutViewer data={data([p])} />)
+    const fills = Array.from(container.querySelectorAll('rect')).map((r) => r.getAttribute('fill'))
+    expect(fills).toContain('rgba(29,78,216,0.18)')
+    expect(fills).toContain('rgba(185,28,28,0.20)')
+  })
+
+  it('the verdict filter dims a family instead of removing it', () => {
+    // Dimming, not hiding: a line that copied its neighbour only reads as
+    // wrong NEXT TO that neighbour, so the context has to stay on the page.
+    const p = page([block([line({ line_id: 'refused', verdict: 'too_different_from_source' })])], {
+      image_url: '/img/p1.jpg',
+    })
+    const { container } = render(<LayoutViewer data={data([p])} />)
+    const before = container.querySelectorAll('rect').length
+
+    fireEvent.click(screen.getByRole('button', { name: /refusée/i }))
+
+    expect(container.querySelectorAll('rect').length).toBe(before)
+    const dimmed = Array.from(container.querySelectorAll('g')).some(
+      (g) => g.getAttribute('opacity') === '0.16',
+    )
+    expect(dimmed).toBe(true)
   })
 
   it('synchronises scroll positions between the two panels', () => {

frontend/src/components/LayoutViewer.tsx

@@ -1,5 +1,11 @@
-import { useCallback, useRef, useState } from 'react'
-import type { LayoutData, LayoutPage } from '../types'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { fetchReviews } from '../api/client'
+import { looksLikeService } from '../lib/iiif'
+import { lineKey, type LineKey } from '../lib/lineKey'
+import { FAMILY, verdictFamily, type VerdictFamily } from '../lib/verdicts'
+import { ReviewPanel } from './ReviewPanel'
+import type { LayoutData, LayoutLine, LayoutPage, LineReview } from '../types'
 
 // ---------------------------------------------------------------------------
 // SVG colour constants (inline — Tailwind classes don't apply to SVG attrs)
@@ -27,9 +33,25 @@ interface SVGOverlayProps {
   opacity: number
   /** When true, a white page rect is drawn first (standalone mode). */
   withBackground: boolean
+  /**
+   * Verdict families to keep at full strength. The others are DIMMED, not
+   * hidden: a line that copied its neighbour only reads as wrong next to
+   * that neighbour, so removing the context removes the evidence.
+   */
+  active: ReadonlySet<VerdictFamily>
+  selectedId: string | null
+  onSelect: (lineId: string) => void
 }
 
-function SVGOverlay({ page, side, opacity, withBackground }: SVGOverlayProps) {
+function SVGOverlay({
+  page,
+  side,
+  opacity,
+  withBackground,
+  active,
+  selectedId,
+  onSelect,
+}: SVGOverlayProps) {
   const { blocks } = page
   const W = page.page_width || blocks.reduce((m, b) => Math.max(m, b.hpos + b.width), 0)
   const H = page.page_height || blocks.reduce((m, b) => Math.max(m, b.vpos + b.height), 0)
@@ -68,13 +90,22 @@ function SVGOverlay({ page, side, opacity, withBackground }: SVGOverlayProps) {
             {block.lines.map((line) => {
               const displayText = side === 'ocr' ? line.ocr_text : line.corrected_text
               const hasHyphen = line.hyphen_role !== 'none'
+              const family = verdictFamily(line)
+              const isSelected = selectedId === line.line_id
+              // Dimmed, not removed — see the `active` prop.
+              const dim = active.has(family) ? 1 : 0.16
 
               if (withBackground) {
                 // SVG-only mode: coloured text on white page
                 const fontSize = Math.max(line.height * 0.7, 1)
                 const textY = line.vpos + line.height * 0.75
                 return (
-                  <g key={line.line_id}>
+                  <g
+                    key={line.line_id}
+                    opacity={dim}
+                    onClick={() => onSelect(line.line_id)}
+                    style={{ cursor: 'pointer' }}
+                  >
                     {line.modified && (
                       <rect
                         x={line.hpos}
@@ -111,15 +142,20 @@ function SVGOverlay({ page, side, opacity, withBackground }: SVGOverlayProps) {
                 const fontSize = Math.max(line.height * 0.72, 1)
                 const textY = line.vpos + line.height * 0.78
                 return (
-                  <g key={line.line_id}>
+                  <g
+                    key={line.line_id}
+                    opacity={dim}
+                    onClick={() => onSelect(line.line_id)}
+                    style={{ cursor: 'pointer' }}
+                  >
                     <rect
                       x={line.hpos}
                       y={line.vpos}
                       width={line.width}
                       height={line.height}
-                      fill={line.modified ? 'rgba(251,191,36,0.70)' : 'rgba(255,255,255,0.78)'}
-                      stroke={line.modified ? 'rgba(217,119,6,0.90)' : 'rgba(148,163,184,0.40)'}
-                      strokeWidth={2}
+                      fill={FAMILY[family].fill}
+                      stroke={FAMILY[family].stroke}
+                      strokeWidth={isSelected ? 6 : 2}
                     />
                     {hasHyphen && (
                       <rect
@@ -161,9 +197,12 @@ interface PagePanelProps {
   page: LayoutPage
   side: 'ocr' | 'corrected'
   overlayOpacity: number
+  active: ReadonlySet<VerdictFamily>
+  selectedId: string | null
+  onSelect: (lineId: string) => void
 }
 
-function PagePanel({ page, side, overlayOpacity }: PagePanelProps) {
+function PagePanel({ page, side, overlayOpacity, active, selectedId, onSelect }: PagePanelProps) {
   const { blocks } = page
   const W = page.page_width || blocks.reduce((m, b) => Math.max(m, b.hpos + b.width), 0)
   const H = page.page_height || blocks.reduce((m, b) => Math.max(m, b.vpos + b.height), 0)
@@ -189,13 +228,31 @@ function PagePanel({ page, side, overlayOpacity }: PagePanelProps) {
             }}
           />
         )}
-        <SVGOverlay page={page} side={side} opacity={overlayOpacity} withBackground={!W || !H} />
+        <SVGOverlay
+          page={page}
+          side={side}
+          opacity={overlayOpacity}
+          withBackground={!W || !H}
+          active={active}
+          selectedId={selectedId}
+          onSelect={onSelect}
+        />
       </div>
     )
   }
 
   // No image: SVG on white background — opacity still controlled by slider
-  return <SVGOverlay page={page} side={side} opacity={overlayOpacity} withBackground={true} />
+  return (
+    <SVGOverlay
+      page={page}
+      side={side}
+      opacity={overlayOpacity}
+      withBackground={true}
+      active={active}
+      selectedId={selectedId}
+      onSelect={onSelect}
+    />
+  )
 }
 
 // ---------------------------------------------------------------------------
@@ -204,11 +261,61 @@ function PagePanel({ page, side, overlayOpacity }: PagePanelProps) {
 
 interface LayoutViewerProps {
   data: LayoutData
+  /**
+   * When given, clicking a line opens the judgement panel and the reader's
+   * verdict is persisted against this job. Omit it and the view stays
+   * read-only — which is what the demo does before a run has a report.
+   */
+  jobId?: string
 }
 
-export function LayoutViewer({ data }: LayoutViewerProps) {
+export function LayoutViewer({ data, jobId }: LayoutViewerProps) {
   const [pageIdx, setPageIdx] = useState(0)
   const [overlayOpacity, setOverlayOpacity] = useState(0.85)
+  // All three families on by default: a reviewer opening the page should see
+  // what the run did before deciding what to hunt for.
+  const [active, setActive] = useState<ReadonlySet<VerdictFamily>>(
+    new Set<VerdictFamily>(['kept', 'refused', 'silent']),
+  )
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [reviews, setReviews] = useState<Map<LineKey, LineReview>>(new Map())
+  // Remembered per browser, not per job: a reviewer working through one
+  // volume pastes the service once and every page of it resolves. The ALTO
+  // does not carry the identifier, so guessing it would be inventing
+  // provenance — the reader supplies it or the panel shows text only.
+  const [iiifService, setIiifService] = useState<string>(
+    () => globalThis.localStorage?.getItem('saknussemm.iiif') ?? '',
+  )
+  const iiifUsable = looksLikeService(iiifService)
+
+  // Judgements already made travel with the job, so a reader can stop and
+  // come back without losing the page they had worked through.
+  useEffect(() => {
+    if (!jobId) return
+    let cancelled = false
+    fetchReviews(jobId)
+      .then(({ reviews: rows }) => {
+        if (cancelled) return
+        setReviews(new Map(rows.map((r) => [lineKey(r.page_id, r.line_id), r])))
+      })
+      .catch(() => {
+        // A review list that will not load must not take the layout with it:
+        // looking at the page is still worth doing.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [jobId])
+
+  const toggleFamily = useCallback((family: VerdictFamily) => {
+    setActive((current) => {
+      const next = new Set(current)
+      if (next.has(family)) next.delete(family)
+      else next.add(family)
+      // Turning the last one off would blank the page and read as a bug.
+      return next.size ? next : current
+    })
+  }, [])
   const leftRef = useRef<HTMLDivElement>(null)
   const rightRef = useRef<HTMLDivElement>(null)
   const syncing = useRef(false)
@@ -239,6 +346,9 @@ export function LayoutViewer({ data }: LayoutViewerProps) {
   }
 
   const currentPage = data.pages[pageIdx] ?? data.pages[0]
+  const selectedLine: LayoutLine | null = selectedId
+    ? (currentPage?.blocks.flatMap((b) => b.lines).find((l) => l.line_id === selectedId) ?? null)
+    : null
   const hasImage = !!currentPage.image_url
 
   return (
@@ -268,6 +378,60 @@ export function LayoutViewer({ data }: LayoutViewerProps) {
             </span>
           </label>
 
+          {/* Verdict filter — dims, never hides. A line that copied its
+              neighbour only reads as wrong NEXT TO that neighbour, so the
+              context has to stay on the page. */}
+          <div className="flex items-center gap-1.5">
+            {(['kept', 'refused', 'silent'] as const).map((family) => {
+              const on = active.has(family)
+              return (
+                <button
+                  key={family}
+                  type="button"
+                  onClick={() => toggleFamily(family)}
+                  aria-pressed={on}
+                  title={`${FAMILY[family].label} — cliquer pour estomper`}
+                  className="font-mono text-[10px] uppercase tracking-wider rounded px-2 py-1
+                             border transition-opacity focus:outline-none focus:ring-1
+                             focus:ring-amber-400"
+                  style={{
+                    borderColor: FAMILY[family].stroke,
+                    color: on ? '#e2e8f0' : '#64748b',
+                    background: on ? FAMILY[family].fill : 'transparent',
+                    opacity: on ? 1 : 0.55,
+                  }}
+                >
+                  {FAMILY[family].label}
+                </button>
+              )
+            })}
+          </div>
+
+          {/* IIIF service — full-resolution line crops, nothing stored */}
+          <label className="flex items-center gap-2">
+            <span className="font-mono text-[10px] text-slate-500 uppercase tracking-wider whitespace-nowrap">
+              IIIF
+            </span>
+            <input
+              type="url"
+              value={iiifService}
+              placeholder="https://…/iiif/image/v3/ark:/12148/…/f1"
+              onChange={(e) => {
+                setIiifService(e.target.value)
+                globalThis.localStorage?.setItem('saknussemm.iiif', e.target.value)
+              }}
+              className={`font-mono text-[11px] bg-slate-900 border rounded px-2 py-1 w-56
+                          text-slate-200 focus:outline-none focus:border-amber-500 ${
+                            iiifService && !iiifUsable ? 'border-red-500' : 'border-slate-600'
+                          }`}
+            />
+            {iiifService && !iiifUsable && (
+              <span className="font-mono text-[10px] text-red-400">
+                base du service, pas une image
+              </span>
+            )}
+          </label>
+
           {/* Page selector */}
           {data.pages.length > 1 && (
             <select
@@ -302,13 +466,51 @@ export function LayoutViewer({ data }: LayoutViewerProps) {
       {/* Dual panels with synchronised scroll */}
       <div className="grid grid-cols-2 divide-x divide-slate-700/40">
         <div ref={leftRef} onScroll={onScrollLeft} className="overflow-auto max-h-[60vh]">
-          <PagePanel page={currentPage} side="ocr" overlayOpacity={overlayOpacity} />
+          <PagePanel
+            page={currentPage}
+            side="ocr"
+            overlayOpacity={overlayOpacity}
+            active={active}
+            selectedId={selectedId}
+            onSelect={setSelectedId}
+          />
         </div>
         <div ref={rightRef} onScroll={onScrollRight} className="overflow-auto max-h-[60vh]">
-          <PagePanel page={currentPage} side="corrected" overlayOpacity={overlayOpacity} />
+          <PagePanel
+            page={currentPage}
+            side="corrected"
+            overlayOpacity={overlayOpacity}
+            active={active}
+            selectedId={selectedId}
+            onSelect={setSelectedId}
+          />
         </div>
       </div>
 
+      {/* Judgement panel — only with a job to persist against, and only once
+          a line is selected. A reviewer who cannot record a verdict produces
+          an impression; one who can produces the ground truth these corpora
+          do not ship. */}
+      {jobId && selectedLine && (
+        <div className="px-4 py-3 border-t border-slate-700/40">
+          <ReviewPanel
+            jobId={jobId}
+            pageId={currentPage.page_id}
+            line={selectedLine}
+            existing={reviews.get(lineKey(currentPage.page_id, selectedLine.line_id)) ?? null}
+            iiifService={iiifUsable ? iiifService : null}
+            onSaved={(review) =>
+              setReviews((current) => {
+                const next = new Map(current)
+                next.set(lineKey(review.page_id, review.line_id), review)
+                return next
+              })
+            }
+            onClose={() => setSelectedId(null)}
+          />
+        </div>
+      )}
+
       {/* Legend */}
       <div className="px-4 py-2.5 border-t border-slate-700/40 flex items-center gap-6 flex-wrap">
         <span className="font-mono text-[10px] text-slate-600 uppercase tracking-wider mr-1">

frontend/src/components/ReviewPanel.test.tsx

@@ -0,0 +1,186 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { LayoutLine, LineReview } from '../types'
+import { ReviewPanel } from './ReviewPanel'
+
+vi.mock('../api/client', () => ({
+  putReviews: vi.fn(),
+}))
+
+import { putReviews } from '../api/client'
+
+const line = (over: Partial<LayoutLine> = {}): LayoutLine => ({
+  line_id: 'TL000323',
+  hpos: 0,
+  vpos: 0,
+  width: 100,
+  height: 20,
+  ocr_text: '1,500 ETANTS : LE NOMBRE DES MORTS',
+  corrected_text: '1,500 ETANTS : LE NOMBRE DES MORTS',
+  modified: false,
+  hyphen_role: 'none',
+  verdict: 'absorbs_previous_line',
+  verdict_detail: null,
+  proposed_text: "AU COURS D'UNE MATINÉE 1,500 ÉTANTS : LE NOMBRE DES MORTS",
+  proposal_declined: true,
+  ...over,
+})
+
+function mount(over: Partial<LayoutLine> = {}, existing: LineReview | null = null) {
+  const onSaved = vi.fn()
+  render(
+    <ReviewPanel
+      jobId="job-1"
+      pageId="PAG_1"
+      line={line(over)}
+      existing={existing}
+      onSaved={onSaved}
+      onClose={vi.fn()}
+    />,
+  )
+  return { onSaved }
+}
+
+describe('ReviewPanel', () => {
+  beforeEach(() => {
+    vi.mocked(putReviews).mockReset()
+  })
+
+  it('shows what was proposed and that it was declined', () => {
+    // The reviewer's most valuable case: something WAS on the table and a
+    // guard refused it. Hiding the proposal would hide whether the refusal
+    // saved a hallucination or threw away a good correction.
+    mount()
+    expect(screen.getByText(/proposé — et refusé/i)).toBeInTheDocument()
+    expect(screen.getByText(/AU COURS D'UNE MATINÉE/)).toBeInTheDocument()
+  })
+
+  it('refuses an empty transcription before it reaches the server', () => {
+    // The text IS the review. An empty one would land in the ground-truth set
+    // asserting nothing, indistinguishable later from a real reading.
+    mount()
+    fireEvent.click(screen.getByRole('button', { name: /ce que je lis/i }))
+
+    expect(screen.getByRole('alert')).toHaveTextContent(/n'affirme rien/i)
+    expect(putReviews).not.toHaveBeenCalled()
+  })
+
+  it('sends the transcription the reader typed', async () => {
+    vi.mocked(putReviews).mockResolvedValue([
+      {
+        page_id: 'PAG_1',
+        line_id: 'TL000323',
+        verdict: 'transcribed',
+        transcription: '1,500 ENFANTS : LE NOMBRE DES MORTS',
+        note: null,
+        reviewed_at: '2026-08-18T10:00:00+00:00',
+      },
+    ])
+    const { onSaved } = mount()
+
+    fireEvent.change(screen.getByRole('textbox', { name: /ce que je lis sur le scan/i }), {
+      target: { value: '1,500 ENFANTS : LE NOMBRE DES MORTS' },
+    })
+    fireEvent.click(screen.getByRole('button', { name: /ce que je lis/i }))
+
+    await waitFor(() => expect(putReviews).toHaveBeenCalledTimes(1))
+    const [jobId, reviews] = vi.mocked(putReviews).mock.calls[0]
+    expect(jobId).toBe('job-1')
+    expect(reviews[0]).toMatchObject({
+      page_id: 'PAG_1',
+      line_id: 'TL000323',
+      verdict: 'transcribed',
+      transcription: '1,500 ENFANTS : LE NOMBRE DES MORTS',
+    })
+    await waitFor(() => expect(onSaved).toHaveBeenCalled())
+  })
+
+  it('grades the engine without needing a transcription', async () => {
+    vi.mocked(putReviews).mockResolvedValue([
+      {
+        page_id: 'PAG_1',
+        line_id: 'TL000323',
+        verdict: 'accepted',
+        transcription: null,
+        note: null,
+        reviewed_at: '2026-08-18T10:00:00+00:00',
+      },
+    ])
+    mount()
+    fireEvent.click(screen.getByRole('button', { name: /le moteur a eu raison/i }))
+    await waitFor(() => expect(putReviews).toHaveBeenCalledTimes(1))
+    expect(vi.mocked(putReviews).mock.calls[0][1][0].verdict).toBe('accepted')
+  })
+
+  it("surfaces the server's own words when it rejects a review", async () => {
+    // A status code the reader cannot act on is worse than no feedback: the
+    // server explains an empty transcription by name, so show that.
+    vi.mocked(putReviews).mockRejectedValue(new Error('a transcribed review must carry the text'))
+    mount()
+    fireEvent.click(screen.getByRole('button', { name: /le moteur a eu tort/i }))
+    await waitFor(() => expect(screen.getByRole('alert')).toHaveTextContent(/must carry the text/i))
+  })
+
+  it('shows an existing judgement as the pressed one', () => {
+    mount(
+      {},
+      {
+        page_id: 'PAG_1',
+        line_id: 'TL000323',
+        verdict: 'refused',
+        transcription: null,
+        note: 'le scan dit ENFANTS',
+        reviewed_at: '2026-08-18T09:00:00+00:00',
+      },
+    )
+    expect(screen.getByRole('button', { name: /le moteur a eu tort/i })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    )
+    expect(screen.getByDisplayValue('le scan dit ENFANTS')).toBeInTheDocument()
+  })
+})
+
+describe('ReviewPanel — le scan en pleine résolution', () => {
+  it('shows the line from IIIF when a service is known', () => {
+    // Judging a word from a downscaled preview means judging ~13 pixels of
+    // newspaper line. The region request costs nothing to store and returns
+    // the scan's native pixels.
+    render(
+      <ReviewPanel
+        jobId="job-1"
+        pageId="PAG_1"
+        line={line({ hpos: 1000, vpos: 2000, width: 500, height: 100 })}
+        existing={null}
+        iiifService="https://example.org/iiif/f1"
+        onSaved={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    )
+    const img = screen.getByRole('img', { name: /ligne TL000323 sur le scan/i })
+    expect(img).toHaveAttribute(
+      'src',
+      'https://example.org/iiif/f1/995,1980,510,140/max/0/default.jpg',
+    )
+  })
+
+  it('falls back to text alone when no service is known', () => {
+    // The ALTO does not carry a IIIF identifier, so its absence is normal and
+    // must not cost the reviewer the rest of the panel.
+    render(
+      <ReviewPanel
+        jobId="job-1"
+        pageId="PAG_1"
+        line={line()}
+        existing={null}
+        onSaved={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    )
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+    // The source and the retained text are identical on a refused line, so
+    // both nodes carry it — the point is that the panel still renders.
+    expect(screen.getAllByText(/1,500 ETANTS/).length).toBeGreaterThan(0)
+  })
+})

frontend/src/components/ReviewPanel.tsx

@@ -0,0 +1,215 @@
+import { useEffect, useState } from 'react'
+
+import { putReviews } from '../api/client'
+import { lineRegionUrl } from '../lib/iiif'
+import type { LayoutLine, LineReview, ReviewVerdict } from '../types'
+
+/**
+ * Where a reader's judgement on one line is made.
+ *
+ * The corpora this demo runs on carry no ground truth — Gallica's `text.txt`
+ * is the same OCR layer as its ALTO — so nothing on disk can say whether a
+ * correction was right or a refusal justified. Only a person reading the scan
+ * can, and this panel is where that reading is captured.
+ *
+ * Three verdicts, and the third is the one that compounds. `accepted` and
+ * `refused` grade what the engine did, which is useful for tuning it.
+ * `transcribed` records what the reader actually read, which stands on its own
+ * whatever the engine decided — and accumulates, line by line, into the ground
+ * truth the bench needs to answer "was the correction right".
+ */
+
+interface ReviewPanelProps {
+  jobId: string
+  pageId: string
+  line: LayoutLine
+  /** The reader's existing judgement on this line, if any. */
+  existing: LineReview | null
+  /**
+   * IIIF Image API service base for this page, when the reader has one.
+   * With it, the line is shown at the scan's NATIVE resolution and nothing is
+   * stored — the alternative is judging a word from a downscaled preview,
+   * which on a newspaper line is roughly 13 pixels tall.
+   */
+  iiifService?: string | null
+  onSaved: (review: LineReview) => void
+  onClose: () => void
+}
+
+const VERDICT_LABEL: Record<ReviewVerdict, string> = {
+  accepted: 'Le moteur a eu raison',
+  refused: 'Le moteur a eu tort',
+  transcribed: 'Voici ce que je lis',
+}
+
+export function ReviewPanel({
+  jobId,
+  pageId,
+  line,
+  existing,
+  iiifService,
+  onSaved,
+  onClose,
+}: ReviewPanelProps) {
+  const [transcription, setTranscription] = useState(existing?.transcription ?? '')
+  const [note, setNote] = useState(existing?.note ?? '')
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  // A reader moves line to line; the fields must follow the selection rather
+  // than carry the previous line's text into the next one's judgement.
+  useEffect(() => {
+    setTranscription(existing?.transcription ?? '')
+    setNote(existing?.note ?? '')
+    setError(null)
+  }, [line.line_id, pageId, existing])
+
+  async function save(verdict: ReviewVerdict) {
+    if (verdict === 'transcribed' && !transcription.trim()) {
+      setError("Une transcription vide n'affirme rien : écrivez ce que vous lisez sur le scan.")
+      return
+    }
+    setSaving(true)
+    setError(null)
+    try {
+      const review: LineReview = {
+        page_id: pageId,
+        line_id: line.line_id,
+        verdict,
+        transcription: transcription.trim() || null,
+        note: note.trim() || null,
+      }
+      const saved = await putReviews(jobId, [review])
+      const mine = saved.find((r) => r.page_id === pageId && r.line_id === line.line_id)
+      if (mine) onSaved(mine)
+    } catch (caught) {
+      setError(caught instanceof Error ? caught.message : String(caught))
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const declined = line.proposal_declined
+
+  return (
+    <aside
+      className="border border-slate-700 bg-slate-800 rounded p-4 flex flex-col gap-3"
+      aria-label={`Jugement sur la ligne ${line.line_id}`}
+    >
+      <header className="flex items-baseline justify-between gap-3">
+        <span className="font-mono text-[10px] uppercase tracking-wider text-slate-400">
+          {line.line_id}
+        </span>
+        <button
+          type="button"
+          onClick={onClose}
+          className="font-mono text-[10px] text-slate-400 hover:text-slate-200"
+        >
+          fermer
+        </button>
+      </header>
+
+      {iiifService && (
+        <figure className="m-0">
+          <img
+            src={lineRegionUrl(iiifService, line)}
+            alt={`Ligne ${line.line_id} sur le scan`}
+            className="w-full rounded border border-slate-600 bg-white"
+          />
+          <figcaption className="font-mono text-[10px] text-slate-500 mt-1">
+            résolution native, servie par IIIF — rien n'est stocké
+          </figcaption>
+        </figure>
+      )}
+
+      <dl className="flex flex-col gap-2 text-xs">
+        <div>
+          <dt className="font-mono text-[10px] uppercase tracking-wider text-slate-500">
+            OCR source
+          </dt>
+          <dd className="font-mono text-slate-200 break-words">{line.ocr_text}</dd>
+        </div>
+        {line.proposed_text && line.proposed_text !== line.ocr_text && (
+          <div>
+            <dt className="font-mono text-[10px] uppercase tracking-wider text-slate-500">
+              Proposé{declined ? ' — et refusé' : ''}
+            </dt>
+            <dd className={`font-mono break-words ${declined ? 'text-red-300' : 'text-blue-300'}`}>
+              {line.proposed_text}
+            </dd>
+          </div>
+        )}
+        <div>
+          <dt className="font-mono text-[10px] uppercase tracking-wider text-slate-500">Retenu</dt>
+          <dd className="font-mono text-slate-100 break-words">{line.corrected_text}</dd>
+        </div>
+        {line.verdict && (
+          <div>
+            <dt className="font-mono text-[10px] uppercase tracking-wider text-slate-500">
+              Verdict du moteur
+            </dt>
+            <dd className="font-mono text-amber-300 break-words">
+              {line.verdict}
+              {line.verdict_detail ? ` — ${line.verdict_detail}` : ''}
+            </dd>
+          </div>
+        )}
+      </dl>
+
+      <label className="flex flex-col gap-1">
+        <span className="font-mono text-[10px] uppercase tracking-wider text-slate-500">
+          Ce que je lis sur le scan
+        </span>
+        <textarea
+          value={transcription}
+          onChange={(e) => setTranscription(e.target.value)}
+          rows={2}
+          spellCheck={false}
+          className="font-mono text-xs bg-slate-900 border border-slate-600 text-slate-100
+                     rounded px-2 py-1 focus:outline-none focus:border-amber-500"
+        />
+      </label>
+
+      <label className="flex flex-col gap-1">
+        <span className="font-mono text-[10px] uppercase tracking-wider text-slate-500">Note</span>
+        <input
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+          className="font-mono text-xs bg-slate-900 border border-slate-600 text-slate-100
+                     rounded px-2 py-1 focus:outline-none focus:border-amber-500"
+        />
+      </label>
+
+      {error && (
+        <p role="alert" className="text-xs text-red-300">
+          {error}
+        </p>
+      )}
+
+      <div className="flex flex-wrap gap-2">
+        {(['accepted', 'refused', 'transcribed'] as const).map((verdict) => (
+          <button
+            key={verdict}
+            type="button"
+            disabled={saving}
+            onClick={() => save(verdict)}
+            aria-pressed={existing?.verdict === verdict}
+            className={`font-mono text-[11px] rounded px-3 py-1.5 border transition-colors
+                        disabled:opacity-50 focus:outline-none focus:ring-1
+                        focus:ring-amber-400 ${
+                          existing?.verdict === verdict
+                            ? 'bg-amber-500 border-amber-400 text-slate-900'
+                            : 'bg-slate-700 border-slate-600 text-slate-200 hover:border-amber-500'
+                        }`}
+          >
+            {VERDICT_LABEL[verdict]}
+          </button>
+        ))}
+      </div>
+
+      {existing?.reviewed_at && (
+        <p className="font-mono text-[10px] text-slate-500">Jugé le {existing.reviewed_at}</p>
+      )}
+    </aside>
+  )
+}

frontend/src/lib/iiif.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+
+import { lineRegionUrl, looksLikeService } from './iiif'
+
+describe('lineRegionUrl', () => {
+  it('passes ALTO coordinates through as the IIIF region', () => {
+    // The two spaces are the same one — a service serving the full scan
+    // declares the page's own dimensions — so no scaling belongs here.
+    const url = lineRegionUrl(
+      'https://example.org/iiif/f1',
+      {
+        hpos: 1000,
+        vpos: 2000,
+        width: 500,
+        height: 100,
+      },
+      0,
+    )
+    expect(url).toBe('https://example.org/iiif/f1/995,2000,510,100/max/0/default.jpg')
+  })
+
+  it('asks for max rather than a fixed width', () => {
+    // Measured against Gallica: a fixed width 400s the moment it would
+    // upscale, and lines are ~70px tall so it almost always would.
+    const url = lineRegionUrl('https://example.org/iiif/f1', {
+      hpos: 0,
+      vpos: 0,
+      width: 100,
+      height: 20,
+    })
+    expect(url).toContain('/max/0/default.jpg')
+    expect(url).not.toMatch(/\/\d+,\/0\//)
+  })
+
+  it('tolerates a trailing slash on the service', () => {
+    const url = lineRegionUrl(
+      'https://example.org/iiif/f1/',
+      {
+        hpos: 0,
+        vpos: 0,
+        width: 10,
+        height: 10,
+      },
+      0,
+    )
+    expect(url).not.toContain('f1//')
+  })
+})
+
+describe('looksLikeService', () => {
+  it('accepts a service base', () => {
+    expect(looksLikeService('https://openapi.bnf.fr/iiif/image/v3/ark:/12148/x/f1')).toBe(true)
+  })
+
+  it('rejects a full image URL, which would nest two region paths', () => {
+    expect(
+      looksLikeService(
+        'https://openapi.bnf.fr/iiif/image/v3/ark:/12148/x/f1/full/max/0/default.jpg',
+      ),
+    ).toBe(false)
+  })
+
+  it('rejects anything that is not a URL', () => {
+    expect(looksLikeService('bpt6k4607951t')).toBe(false)
+  })
+})

frontend/src/lib/iiif.ts

@@ -0,0 +1,50 @@
+/**
+ * IIIF Image API region URLs — a line's own pixels, without storing a thing.
+ *
+ * ALTO coordinates and the IIIF region parameter live in the SAME space: a
+ * service serving the full scan declares exactly the page's own dimensions
+ * (measured on Gallica: `info.json` says 6802×9121 for an ALTO page of
+ * 6802×9121). So the coordinates go through verbatim — no scale, no
+ * transform, and no local derivative to crop.
+ *
+ * That matters beyond convenience. Cropping a DOWNSCALED derivative locally
+ * is how a line ends up cut from the wrong place: Gallica's `!1600,1600`
+ * preview is 17.5% of the ALTO space, so a line at hpos=4798 falls off an
+ * image 1193 pixels wide, and the crop comes back blank with nothing
+ * downstream any the wiser.
+ */
+
+export interface Region {
+  hpos: number
+  vpos: number
+  width: number
+  height: number
+}
+
+/**
+ * `size` is `max`, deliberately.
+ *
+ * Asking for a fixed width is refused with HTTP 400 the moment it would
+ * UPSCALE the region — measured against Gallica, whose lines are ~70px tall:
+ * `/1200,/` returns 400, `/max/` returns 200. IIIF 3.0 requires an explicit
+ * `^` prefix to allow upscaling, and a line does not need it: its native
+ * pixels are exactly what a reader wants to see.
+ */
+export function lineRegionUrl(service: string, region: Region, marginRatio = 0.2): string {
+  const marginX = Math.round(region.width * 0.01)
+  const marginY = Math.round(region.height * marginRatio)
+  const x = Math.max(region.hpos - marginX, 0)
+  const y = Math.max(region.vpos - marginY, 0)
+  const w = region.width + 2 * marginX
+  const h = region.height + 2 * marginY
+  return `${service.replace(/\/+$/, '')}/${x},${y},${w},${h}/max/0/default.jpg`
+}
+
+/** Whether a pasted string looks like an Image API service base, not a full image URL. */
+export function looksLikeService(value: string): boolean {
+  const trimmed = value.trim()
+  if (!/^https?:\/\//i.test(trimmed)) return false
+  // A full image URL already carries region/size/rotation/quality; using it as
+  // a base would produce nonsense like `.../full/max/0/default.jpg/12,3,4,5/max/...`.
+  return !/\/(full|square|\d+,\d+,\d+,\d+)\/[^/]+\/\d+\/[^/]+\.\w+$/i.test(trimmed)
+}

frontend/src/lib/verdicts.ts

@@ -0,0 +1,45 @@
+// ---------------------------------------------------------------------------
+// Verdict palette — what the engine decided, and why
+// ---------------------------------------------------------------------------
+//
+// Three families, because a reviewer scans for three different things and
+// should not have to read a legend to tell them apart:
+//
+//   kept      the correction survived every guard
+//   refused   something was proposed and a guard declined it — the cases
+//             worth a human eye, since each is either a caught hallucination
+//             or a good correction thrown away
+//   silent    nothing was proposed, or nothing changed; no judgement to make
+//
+// Colours are the proof-reader's two pencils: blue marks what stands, red
+// marks what was struck out. Amber sits between them for a line the engine
+// never got an answer for.
+
+export type VerdictFamily = 'kept' | 'refused' | 'silent'
+
+const REFUSAL_CODES = new Set([
+  'too_different_from_source',
+  'closer_to_previous_line',
+  'closer_to_next_line',
+  'absorbs_previous_line',
+  'absorbs_next_line',
+  'hyphen_pair_fallback',
+  'boundary_migration_forward',
+  'boundary_migration_backward',
+  'adjacent_duplicate_detected',
+  'adjacent_duplicate_pair_atomicity',
+  'orphan_hyphen_completed',
+  'hyphen_unit_fallback',
+])
+
+export function verdictFamily(line: { verdict: string | null; modified: boolean }): VerdictFamily {
+  if (line.verdict && REFUSAL_CODES.has(line.verdict)) return 'refused'
+  if (line.verdict === 'all_attempts_exhausted') return 'silent'
+  return line.modified ? 'kept' : 'silent'
+}
+
+export const FAMILY = {
+  kept: { stroke: '#1d4ed8', fill: 'rgba(29,78,216,0.18)', label: 'Retenue' },
+  refused: { stroke: '#b91c1c', fill: 'rgba(185,28,28,0.20)', label: 'Refusée' },
+  silent: { stroke: '#a1a1aa', fill: 'rgba(161,161,170,0.10)', label: 'Sans objet' },
+} as const

frontend/src/types/api.generated.ts

@@ -289,6 +289,32 @@ export interface paths {
     patch?: never
     trace?: never
   }
+  '/api/jobs/{job_id}/reviews': {
+    parameters: {
+      query?: never
+      header?: never
+      path?: never
+      cookie?: never
+    }
+    /** Get Reviews */
+    get: operations['get_reviews_api_jobs__job_id__reviews_get']
+    /**
+     * Put Reviews
+     * @description Record or replace judgements on lines of this job.
+     *
+     *     Idempotent per line: sending the same line twice replaces its review
+     *     rather than appending, so a reader who changes their mind is not fighting
+     *     an append-only log. The timestamp is stamped here rather than trusted
+     *     from the client — a review's date is a fact about the server.
+     */
+    put: operations['put_reviews_api_jobs__job_id__reviews_put']
+    post?: never
+    delete?: never
+    options?: never
+    head?: never
+    patch?: never
+    trace?: never
+  }
 }
 export type webhooks = Record<string, never>
 export interface components {
@@ -397,6 +423,23 @@ export interface components {
       /** Error */
       error?: string | null
     }
+    /**
+     * LineReview
+     * @description One reader's judgement on one line.
+     */
+    LineReview: {
+      /** Page Id */
+      page_id: string
+      /** Line Id */
+      line_id: string
+      verdict: components['schemas']['ReviewVerdict']
+      /** Transcription */
+      transcription?: string | null
+      /** Note */
+      note?: string | null
+      /** Reviewed At */
+      reviewed_at?: string | null
+    }
     /** ListModelsRequest */
     ListModelsRequest: {
       provider: components['schemas']['Provider']
@@ -432,6 +475,27 @@ export interface components {
      * @enum {string}
      */
     Provider: 'openai' | 'anthropic' | 'mistral' | 'google'
+    /**
+     * ReviewBatch
+     * @description Reviews arrive in batches: a reader works through a page, not a line.
+     */
+    ReviewBatch: {
+      /** Reviews */
+      reviews: components['schemas']['LineReview'][]
+    }
+    /**
+     * ReviewVerdict
+     * @description What the reader concluded about the engine's decision on this line.
+     * @enum {string}
+     */
+    ReviewVerdict: 'accepted' | 'refused' | 'transcribed'
+    /** ReviewsResponse */
+    ReviewsResponse: {
+      /** Job Id */
+      job_id: string
+      /** Reviews */
+      reviews: components['schemas']['LineReview'][]
+    }
     /** ValidationError */
     ValidationError: {
       /** Location */
@@ -837,4 +901,70 @@ export interface operations {
       }
     }
   }
+  get_reviews_api_jobs__job_id__reviews_get: {
+    parameters: {
+      query?: never
+      header?: never
+      path: {
+        job_id: string
+      }
+      cookie?: never
+    }
+    requestBody?: never
+    responses: {
+      /** @description Successful Response */
+      200: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['ReviewsResponse']
+        }
+      }
+      /** @description Validation Error */
+      422: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['HTTPValidationError']
+        }
+      }
+    }
+  }
+  put_reviews_api_jobs__job_id__reviews_put: {
+    parameters: {
+      query?: never
+      header?: never
+      path: {
+        job_id: string
+      }
+      cookie?: never
+    }
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['ReviewBatch']
+      }
+    }
+    responses: {
+      /** @description Successful Response */
+      200: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['ReviewsResponse']
+        }
+      }
+      /** @description Validation Error */
+      422: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['HTTPValidationError']
+        }
+      }
+    }
+  }
 }

frontend/src/types/index.ts

@@ -211,6 +211,31 @@ export interface LayoutLine {
   corrected_text: string
   modified: boolean
   hyphen_role: 'none' | 'HypPart1' | 'HypPart2'
+  /**
+   * Why the line ended up as it did — the guard code, or the decision status
+   * when no guard spoke. Geometry alone cannot distinguish "nothing was
+   * proposed" from "a hallucination was refused", and a reviewer needs to.
+   * `null` when the job carries no report yet.
+   */
+  verdict: string | null
+  verdict_detail: string | null
+  /** What the producer actually returned, before the engine judged it. */
+  proposed_text: string | null
+  /** A proposal was on the table and the engine declined it — the case worth reading. */
+  proposal_declined: boolean
+}
+
+/** How a reader graded the engine on one line. */
+export type ReviewVerdict = 'accepted' | 'refused' | 'transcribed'
+
+export interface LineReview {
+  page_id: string
+  line_id: string
+  verdict: ReviewVerdict
+  /** What the reader read on the scan. Required for `transcribed`. */
+  transcription?: string | null
+  note?: string | null
+  reviewed_at?: string | null
 }
 
 export interface LayoutBlock {

tools/run_corpus_arms.py

@@ -0,0 +1,261 @@
+"""Run a corpus through the demo's own JobRunner, one arm at a time.
+
+    python tools/run_corpus_arms.py <corpus-root> <arm> [concurrency]
+
+Arms:
+
+    small-text        mistral-small-latest, no image
+    small-vision      mistral-small-latest, per-line crops
+    ministral-text    ministral-8b-latest, no image
+    ministral-vision  ministral-8b-latest, per-line crops
+
+`<corpus-root>` is scanned for ``alto.xml`` files, each with an optional
+``image.jpg`` beside it — the layout a digital library's page-by-page export
+produces, and the shape ``gallica_multicolumn`` writes.
+
+This drives ``JobRunner`` rather than the HTTP API: same producer assembly,
+same guards, same output writer, no server to stand up. The key is read from
+the macOS keychain and never appears in a flag, an environment dump, or an
+artefact — a flag would land in shell history and in the process list.
+
+One JSON per page under ``<corpus-root>/../arm-results/<arm>/``, so an
+interrupted run resumes and nothing measured is lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import subprocess
+import sys
+import time
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "backend"))
+
+from saknussemm.formats.loader import build_document_manifest
+
+from app.jobs.runner import JobRunner, page_image_assets
+from app.jobs.store import JobStore
+from app.providers.mistral_multimodal import MistralMultimodalProvider
+from app.providers.mistral_provider import MistralProvider
+from app.storage.output_writer import FilesystemOutputWriter
+
+ARMS: dict[str, tuple[str, bool]] = {
+    "small-text": ("mistral-small-latest", False),
+    "small-vision": ("mistral-small-latest", True),
+    "ministral-text": ("ministral-8b-latest", False),
+    "ministral-vision": ("ministral-8b-latest", True),
+}
+
+
+def keychain_key() -> str:
+    return subprocess.run(
+        ["security", "find-generic-password", "-a", "marcel", "-s", "mistral-api-key", "-w"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+
+
+def find_pages(root: Path) -> list[tuple[str, Path, Path | None]]:
+    """``(label, alto path, image path or None)`` for every page under *root*."""
+    pages = []
+    for alto in sorted(root.rglob("alto.xml")):
+        label = f"{alto.parent.parent.name}_{alto.parent.name.split('_')[-1]}"
+        image = alto.parent / "image.jpg"
+        pages.append((label, alto, image if image.exists() else None))
+    return pages
+
+
+async def run_one(
+    arm: str,
+    label: str,
+    alto: Path,
+    image: Path | None,
+    api_key: str,
+    results: Path,
+    sem: asyncio.Semaphore,
+) -> dict | None:
+    target = results / f"{label}.json"
+    if target.exists():
+        return json.loads(target.read_text())
+
+    model, wants_image = ARMS[arm]
+    if wants_image and image is None:
+        return None
+
+    async with sem:
+        from app.schemas import Provider
+
+        store = JobStore()
+        job_id = store.create_job(provider=Provider.MISTRAL, model=model)
+        manifest = build_document_manifest([(alto, alto.name)])
+
+        images = None
+        if wants_image:
+            images = page_image_assets(manifest, {alto.parent.name.lower(): image})
+            if not images:
+                # The demo keys images by source-file stem; this corpus names
+                # every file `alto.xml`, so map it explicitly by page instead of
+                # letting the helper's stem lookup miss silently.
+                import hashlib
+
+                from saknussemm.core.schemas import ImageAsset
+
+                digest = hashlib.sha256(image.read_bytes()).hexdigest()
+                images = {
+                    page.page_id: ImageAsset(
+                        page_id=page.page_id,
+                        uri=str(image),
+                        sha256=digest,
+                        media_type="image/jpeg",
+                    )
+                    for page in manifest.pages
+                }
+
+        out_dir = results / "outputs" / label
+        out_dir.mkdir(parents=True, exist_ok=True)
+        writer = FilesystemOutputWriter(out_dir)
+        runner = JobRunner(store)
+
+        started = time.perf_counter()
+        await runner.run(
+            job_id=job_id,
+            document_manifest=manifest,
+            provider_name="mistral",
+            api_key=api_key,
+            model=model,
+            output_writer=writer,
+            source_files={alto.name: alto},
+            provider=(MistralMultimodalProvider() if wants_image else MistralProvider()),
+            page_images=images,
+            timeout_seconds=0,
+        )
+        elapsed = time.perf_counter() - started
+
+        job = store.get_job(job_id)
+        report = job.report if job else None
+        record: dict = {
+            "arm": arm,
+            "page": label,
+            "model": model,
+            "wants_image": wants_image,
+            "seconds": round(elapsed, 1),
+            "status": job.status.value if job else "unknown",
+            "error": job.error if job else None,
+            "lines": job.total_lines if job else 0,
+            "fallbacks": job.fallbacks if job else 0,
+            "retries": job.retries if job else 0,
+        }
+        if report is not None:
+            reasons = Counter(
+                line.decision.reason.code
+                for line in report.lines
+                if line.decision.reason is not None
+            )
+            usage = report.usage
+            record.update(
+                input_tokens=getattr(usage, "input_tokens", 0) if usage else 0,
+                output_tokens=getattr(usage, "output_tokens", 0) if usage else 0,
+                reasons=dict(reasons),
+                statuses=dict(Counter(ln.decision.status for ln in report.lines)),
+                changed=sum(1 for ln in report.lines if ln.decision.final_text != ln.source_text),
+                blocked=sum(
+                    1
+                    for ln in report.lines
+                    if ln.decision.reason is not None
+                    and ln.proposal is not None
+                    and ln.proposal.output_text != ln.source_text
+                ),
+                format_losses=dict(report.format_losses or {}),
+                samples=[
+                    {"src": ln.source_text, "out": ln.decision.final_text}
+                    for ln in report.lines
+                    if ln.decision.final_text != ln.source_text
+                ][:5],
+                refused=[
+                    {
+                        "reason": ln.decision.reason.code,
+                        "src": ln.source_text,
+                        "llm": ln.proposal.output_text,
+                    }
+                    for ln in report.lines
+                    if ln.decision.reason is not None
+                    and ln.proposal is not None
+                    and ln.proposal.output_text != ln.source_text
+                ][:5],
+            )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(record, ensure_ascii=False, indent=1))
+    print(
+        f"[{arm}] {label:26s} {record['status']:10s} {record.get('lines', 0):5d}L "
+        f"{elapsed:6.1f}s {record.get('input_tokens', 0):8d}in/"
+        f"{record.get('output_tokens', 0):7d}out",
+        flush=True,
+    )
+    return record
+
+
+async def main() -> None:
+    if len(sys.argv) < 3:
+        print(__doc__)
+        raise SystemExit(2)
+    root = Path(sys.argv[1]).resolve()
+    arm = sys.argv[2]
+    concurrency = int(sys.argv[3]) if len(sys.argv) > 3 else 3
+    if arm not in ARMS:
+        raise SystemExit(f"unknown arm {arm!r}; pick from {list(ARMS)}")
+
+    results = root.parent / "arm-results" / arm
+    results.mkdir(parents=True, exist_ok=True)
+    pages = find_pages(root)
+    print(f"arm {arm} — {len(pages)} pages, concurrency {concurrency}", flush=True)
+
+    api_key = keychain_key()
+    sem = asyncio.Semaphore(concurrency)
+    records = await asyncio.gather(
+        *(run_one(arm, label, alto, image, api_key, results, sem) for label, alto, image in pages),
+        return_exceptions=True,
+    )
+
+    good = [r for r in records if isinstance(r, dict)]
+    failed = [r for r in records if isinstance(r, BaseException)]
+    totals: Counter[str] = Counter()
+    reasons: Counter[str] = Counter()
+    for record in good:
+        for field in (
+            "lines",
+            "input_tokens",
+            "output_tokens",
+            "changed",
+            "blocked",
+            "fallbacks",
+            "retries",
+        ):
+            totals[field] += record.get(field, 0)
+        reasons.update(record.get("reasons", {}))
+    print(f"\n=== {arm} ===")
+    print(f"pages ok {len(good)}, raised {len(failed)}")
+    print(f"totals {dict(totals)}")
+    print(f"reasons {dict(reasons)}")
+    for exc in failed[:3]:
+        print(f"  raised: {type(exc).__name__}: {exc}")
+    (results.parent / f"{arm}-summary.json").write_text(
+        json.dumps(
+            {
+                "arm": arm,
+                "pages": len(good),
+                "raised": len(failed),
+                "totals": dict(totals),
+                "reasons": dict(reasons),
+            },
+            ensure_ascii=False,
+            indent=1,
+        )
+    )
+
+
+asyncio.run(main())