rag-service/openspec/changes/archive/2026-09-21-ocr-ingest-integration/tasks.md

Tasks: OCR Ingest Integration

Forecast

Estimate: 3,400–4,300 lines.

Decision needed before apply: No Chained PRs recommended: Yes Chain strategy: feature-branch-chain 400-line budget risk: High

Tracker feature/ocr-ingest-integration is draft/no-merge and sole main target. PR1 targets tracker; children target predecessors. Coverage: 17 requirements/34 scenarios (O10/P12/V12).

Units: command; harness; rollback

1 Migration: tsx --test tests/catalog/migration-002.test.ts; N/A schema-only; drop OCR schema 2 Repository: tsx --test tests/catalog/repository-ocr.test.ts; fake pool; revert candidate/leases 3 Extraction: tsx --test tests/parsers/pdf-pages.test.ts; PDF spike; revert parser/fixtures 4 Detection: tsx --test tests/ocr/detection.test.ts; mixed PDF; revert transforms 5 Service: pytest ocr-service/tests -k auth; curl 401/409; remove ocr-service 6 Render: pytest ocr-service/tests -k render; Docker PNG; revert wrapper/image 7 Client: tsx --test tests/ocr/client.test.ts; retry stub; revert client/artifacts 8 Dispatcher: tsx --test tests/ocr/dispatcher.test.ts; curl 202/status; revert routing 9 Review: tsx --test tests/ocr/review.test.ts; curl review/409; revert review/routes 10 Approval: tsx --test tests/ocr/approval.test.ts; playground approval; revert indexing/UI 11 Retention: tsx --test tests/ocr/retention.test.ts; fake-fs sweep; revert retention 12 Config: npm run check; N/A static-only; revert config/docs 13 E2E: npm test; production OCR flow; disable OCR flag

1 Persistence (Units 1–2; O2/O3)

• 1.1 RED: duplicate pending, lease recovery, review transitions
• 1.2 GREEN: migrations/002_ocr_review.sql schema and unique index
• 1.3 GREEN: src/modules/catalog/repository.ts candidates and leases
• 1.4 REFACTOR after green

2 Extraction (Units 3–4; P1–P4)

• 2.1 Spike scripts/spike-pdfjs.ts for Node 22 parser
• 2.2 RED: PDF-only routing; text files never execute; unsupported build/script formats; pages, blanks, hashes, risks
• 2.3 GREEN: tests/fixtures/ocr/ and src/modules/parsers/parser-registry.ts
• 2.4 GREEN: src/modules/ocr/detection.ts thresholds
• 2.5 GREEN: src/modules/ocr/composition.ts text, hashes, risks

3 OCR Service (Units 5–6; P5/P6)

• 3.1 RED HTTP: bearer 401; idempotency/conflict 409; allowlist; limits 413/422; pressure 429; no-retry; integrity mismatch
• 3.2 GREEN: ocr-service/ API, queue, allowlist, limits, health
• 3.3 GREEN: PaddleOCR 3.4.0, 200 DPI, schema, stub
• 3.4 GREEN: ocr-service/Dockerfile pinned wheels/models/resources

4 Orchestration (Units 7–8; O1–O4)

• 4.1 RED HTTP: flag-off 201; OCR 202/status; OCR-down fail-closed; catalog-down 503; retries/integrity
• 4.2 GREEN: src/modules/ocr/client.ts retries and integrity
• 4.3 GREEN: src/modules/ocr/artifacts.ts originals, manifest, sweep
• 4.4 GREEN: src/modules/ocr/dispatcher.ts leases; src/modules/catalog/reconciler.ts
• 4.5 GREEN: src/modules/ingest/service.ts branch; src/app.ts upload/status

5 Review (Units 9–10; V1–V4)

• 5.1 RED: auth/premature access; atomic corrections/stale 409; new/reusable activation race; reject/no embeddings
• 5.2 GREEN: src/modules/ocr/review.ts view, corrections, conflicts
• 5.3 GREEN: src/modules/ocr/indexing.ts CAS; new/reusable activate_requested=true activates, false stays ready
• 5.4 GREEN: rejection and public/playground/ review UI

6 Retention/Deploy (Units 11–12; O5/V5)

• 6.1 RED: TTL/CAS/resume/active protection; flag-off native-only and candidate invisibility
• 6.2 GREEN: src/modules/ocr/retention.ts
• 6.3 GREEN: src/api/openapi.ts OCR/status/review contracts
• 6.4 GREEN: src/config/env.ts, Dockerfile; follow docs/CONTRATO_CICLO_VIDA_Y_OCR.md (read-only)

7 E2E (Unit 13; V6)

• 7.1 E2E: native 201; scanned 202→review→approve→active; mixed
• 7.2 E2E: resend, OCR-down fail-closed, catalog-down 503
• 7.3 Gate: check, build, test, offline pytest
• 7.4 Production: flag-off verify→enable→FacturaTech 34 entries; CBG04a/FAT07/DSAU08/NSAV06