rag-service/openspec/specs/ocr-review-workflow/spec.md

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