Review in the viewer (S4)
The review screen turns the read-only evidence viewer into the place where a person checks,
corrects and verifies a document. It lives at /runs/{id} (and
/workflows/{workflow}/runs/{id}); everything it does goes through the API below, so a script can
review exactly like the screen does.
The effective value
The extraction result of a run (T08) never changes. Every action a reviewer takes appends a
review_decision (append-only: UPDATE and DELETE fail in the database) and rewrites the
field_override projection. The values of both are sealed with the run's data key (T50): a certified
deletion or a ZDR sweep destroys that key, and the history and the review then show the decisions
with their values as null and redacted: true (docs/security/encryption.md). What the screen, the verification and the later consumers (T33, T36,
T37, T40, T42) read is the effective result: the extraction with the overrides applied.
| Action | Effective field |
|---|---|
| none | the extracted value; review_state is approved (auto-approved or verified by the pipeline) or needs_review |
approve |
the value it had (a correction stays a correction); reviewed: true |
correct |
the typed value, status: human_override, review_state: corrected; original keeps the extracted value; the evidence is the one the reviewer chose (or none) |
mark_absent |
no value (status: not_found), review_state: absent |
reject |
no value, review_state: rejected |
Rows of a table have a stable row_id: r0..rN for the extracted rows and u_<id> for the rows a
reviewer adds. Overrides are keyed by the stable path (line_items[r2].amount), so adding or
deleting a row never moves another row's decisions. The API accepts both the stable path and the
positional one (line_items[2].amount names the third row now).
final_result is the snapshot saved when the document is verified (POST /v1/runs/{id}:approve):
the effective fields with their review_state, the nested data, the validations recomputed on
the effective data and the counters. Its JSON Schema, and those of the decision log and of the two
events, are in schemas/review/ (generated from src/extractit/review/contracts.py,
checked by make contracts). Fixtures: tests/fixtures/review/.
API
| Route | What it does |
|---|---|
GET /v1/runs/{id}/review |
effective fields, validations, state, counters (?below=), ETag |
PATCH /v1/runs/{id}/fields/{path} |
{action: approve\|correct\|mark_absent\|reject, value?, region?, reason_code?, time_spent_ms?, locale?} with If-Match; answers the field and the recomputed validations |
POST /v1/runs/{id}/rows |
{table_path, index} adds an empty row (201, the whole review) |
DELETE /v1/runs/{id}/rows/{path} |
deletes a row (line_items[2], line_items[r2]) |
POST /v1/runs/{id}:approve |
verifies the document; one review.completed and one extraction.corrected per corrected field in the outbox, in the same transaction; idempotent |
POST /v1/runs/{id}:reject |
rejects the document; idempotent |
GET /v1/runs/{id}/review/history?path= |
the decisions on a field, in order |
GET /v1/review/next?workflow_id=&after= |
the next run of the workflow whose review is still open |
Mutations need review:act (Reviewer, Admin, Owner; a Viewer reads but every mutation is 403) and
If-Match with the review's weak ETag W/"sha256(extraction_id:last_seq)[:16]":
- missing → 428
precondition-required; - stale → 412
etag-mismatch(nothing is written; the body carries the currentetagand, for a field, itscurrentstate); - a value that does not fit the field's type → 422
invalid-field-valuewitherrors[].pointer(#/value,#/region,#/index); - approving while a blocking rule fails → 409
blocking-rule-failing, unlessacknowledge_blocking: truewith areason; - any change to a verified or rejected review → 409
conflict; another tenant's run → 404.
Values are validated and normalized with the normalizers of T07 according to the type of the
output contract: 4.594,62 with locale: es-ES is 4594.62. Rules are re-evaluated on every
change through the RuleEvaluator port (review/rules_adapter.py imports extractit.rules
lazily and runs the deterministic rules of the run's workflow version or one-shot rules; AI and
external rules are not re-run inside a 300 ms request).
The region as human evidence
region is {page, bbox | polygon} in page_display_norm_v1 (normalized 0..1 of the displayed
page). The server selects the DocIR words whose overlap with the region covers at least 50 % of
their area, builds quote and word_range, and passes the value and those words through the
grounding verifier (T07) to set verification. Without value the value is read from the words.
A region without words keeps the box as evidence unverified and the response carries the warning
no_words_in_region; a value the words do not hold is unverified or contradicted with
value_not_in_region.
Keyboard
Cmd instead of Ctrl on macOS. Nothing acts while a text field has the focus, except
Ctrl/⌘+Enter and Esc. ? shows this table in the app.
| Key | Action |
|---|---|
J / K |
next / previous field (of the current filter) |
Enter |
approve the field and move to the next pending one |
A |
approve the field |
E |
edit the value (Enter saves, Esc cancels) |
D |
mark the field absent |
X |
reject the field |
R |
pick the region with the keyboard: arrows move over the words, Shift+arrow extends, Enter confirms, Esc cancels |
G |
go to the field's evidence |
Ctrl/⌘+Enter |
verify the document |
Shift+Enter |
verify the document and open the next one |
Shift+→ / Shift+← |
next / previous document |
? |
show the shortcuts |
Esc |
cancel the editor, the region picker or a dialog |
With the pointer, Elegir región (or R after the keyboard flow) lets you drag a rectangle over
the words of the page.
Filters
filter (pending, the default, or all), below (confidence threshold, 0.80 by default) and
unverified live in the URL, so a link reopens the same view; the counters next to them are the
ones the API computes (counts in GET .../review).
- Pendientes: no decision yet, and confidence below the threshold, or a primary evidence whose
verification is not
verified, or a failed validation citing the field's evidence, orneeds_reviewfrom the extraction. - No verificados: fields no human has decided on.
The marks next to a value are ƒ (derived), ⇢ (taken from metadata) and ⚠ (evidence no
verification backs).
Time per field
The client measures the time between selecting a field and deciding on it
(performance.now(), capped at 10 minutes per decision) and sends it as time_spent_ms; the
review keeps the sum.