# OCR Review Workflow Specification

## Purpose

Define authenticated review, atomic correction, activation, and retention.

## Requirements

### Requirement: Mandatory Authenticated Review

OCR versions MUST remain `review_required` and non-retrievable until approved. Status, review, images, approval, and rejection MUST require the administrator token.

#### Scenario: Reviewer inspects a candidate

- GIVEN all documents passed the version gate
- WHEN an authorized reviewer opens review
- THEN it MUST show image, native text, raw OCR, boxes, confidence, differences, and risks

#### Scenario: Unauthorized or premature access

- GIVEN credentials fail or the version is not reviewable
- WHEN review or decision is requested
- THEN it MUST reject the request without exposing artifacts or changing state

### Requirement: Atomic Optimistic Corrections

Approval MUST validate `candidateSha256`, unique line identities, and every `expectedLineSha256` before changes. Reviewed text SHALL be immutable.

#### Scenario: Valid corrections commit together

- GIVEN hashes are current and correction targets are unique
- WHEN approval is submitted
- THEN all replacements MUST commit together with reviewer, time, and resulting hashes

#### Scenario: Stale or conflicting correction

- GIVEN any candidate, line, identity, or box is stale or duplicated
- WHEN approval is submitted
- THEN the system MUST return `409` without corrections or state transition

### Requirement: Approval and Activation Gate

Approval MUST cover the version, derive final hashes, and move `review_required` to `indexing` before chunking. Activation SHALL use Point 2 verification and the expected active version.

#### Scenario: Approved content becomes active

- GIVEN corrections are valid and the expected active version is current
- WHEN indexing and point verification succeed
- THEN the new version MUST become active atomically and the previous one superseded
- AND only reviewed content MAY be retrieved

#### Scenario: Active version changes during review

- GIVEN another version activates during review
- WHEN approved indexing completes
- THEN the candidate MUST remain `ready`, return `409 ACTIVE_VERSION_CHANGED`, and not replace it

#### Scenario: Reusable content already exists

- GIVEN final content, fingerprint, and metadata match a reusable version
- WHEN approval checks the active-version precondition
- THEN the candidate MUST be `rejected` with `DUPLICATE_REUSABLE_VERSION`
- AND only the existing version MAY be activated

### Requirement: Rejection and Failure Isolation

Rejection MUST produce `rejected`, preserve temporary audit evidence, and generate no embeddings. Failed or rejected candidates SHALL never alter the active version.

#### Scenario: Reviewer rejects candidate

- GIVEN a version is `review_required`
- WHEN an authorized reviewer rejects it
- THEN it MUST become `rejected` with audit data and no indexing

### Requirement: Retention Safety

Private artifacts MUST use `0600` permissions and verifiable hashes. The system MUST retain review 30 days, failed/rejected artifacts 7 days, review images 7 days post-decision, OCR copies until transfer or 24 hours, and active artifacts until 30 days after supersession. Cleanup MUST be idempotent and never delete active versions.

#### Scenario: Review expires

- GIVEN a version remains `review_required` for 30 days
- WHEN daily retention runs exclusively
- THEN it MUST become `rejected` with `REVIEW_EXPIRED` before removal

#### Scenario: Active artifacts are protected

- GIVEN an active version is past a TTL
- WHEN retention runs concurrently with review or purge
- THEN its original, reviewed text, raw OCR, and manifest MUST remain
- AND cleanup MUST not escape the version directory or expose a public URL

#### Scenario: Interrupted cleanup resumes

- GIVEN deletion stopped after retention entered its deleting state
- WHEN cleanup runs again
- THEN deletion MUST resume safely and finish in the deleted state without affecting other versions

### Requirement: Human-Approved Production Acceptance

The release MUST prove corrected content after approval; confidence SHALL NOT authorize activation.

#### Scenario: FacturaTech acceptance succeeds

- GIVEN the real FacturaTech PDF has been reviewed and its 34 entries approved
- WHEN the version becomes active and retrieval is queried
- THEN all 34 entries and `CBG04a`, `FAT07`, `DSAU08`, and `NSAV06` MUST be returned exactly