Ingestion guide's AWS Textract recipe reads only the first GetDocumentTextDetection page and never checks JobStatus, silently truncating multi-page OCR text (F-W1-DOCS-TRAIN-13) #883

Wave 3 · group W3 Docs · highest severity Medium · 1 finding(s) · effort docs fix

Summary

The OCR recipe makes one get_document_text_detection call, writes the LINE blocks it returns and runs forgelm ingest on the result. Textract returns at most 1,000 blocks per call — PAGE, LINE and WORD blocks all count — plus a NextToken for the rest, so a typical multi-page scan is cut short with no error and the truncated text becomes training data.

Primary finding

F-W1-DOCS-TRAIN-13 — The Textract recipe silently truncates paginated OCR output

severity Medium · confidence high · checked against the AWS API reference

What happens. docs/guides/ingestion.md:634-650 (Turkish mirror docs/guides/ingestion-tr.md:652-668); the single call is at EN :644 / TR :662. The snippet never follows NextToken and never checks JobStatus, so a job that is still IN_PROGRESS, FAILED or only a PARTIAL_SUCCESS looks the same as a finished one. It also uses $JOB_ID without showing where it comes from: the start-document-text-detection call in step 2 does not capture the returned JobId.

Where.

• docs/guides/ingestion.md:634-650 (single call at :644)
• docs/guides/ingestion-tr.md:652-668 (single call at :662)

Evidence (re-verified on 2026-10-09).

• AWS Textract API reference, GetDocumentTextDetection: results are paginated; when a response includes NextToken, call the operation again with it to get the next set; MaxResults defaults to 1,000 (https://docs.aws.amazon.com/textract/latest/APIReference/API_GetDocumentTextDetection.html).
• The source review ran the embedded snippet against a two-page stub client: it made one call, printed only the first page and exited normally.
• Both guide pages are unchanged on development.

Recommended fix. Capture the job id (JOB_ID=$(aws textract start-document-text-detection … --query JobId --output text)), wait until JobStatus is no longer IN_PROGRESS (or point to AWS's polling / SNS pattern), stop with an error on FAILED, print a warning on PARTIAL_SUCCESS, and loop over NextToken so every page's LINE blocks are written in order before forgelm ingest runs.

Acceptance criteria

• The recipe follows NextToken until it is absent and writes every LINE block in order.
• A failed or still-running job stops the recipe before forgelm ingest; a partial success is reported.
• The snippet shows where JOB_ID comes from.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• The finding is resolved or explicitly closed with a reason.

_{Found by the September 2026 independent review of ForgeLM against commit cab2947 and re-verified against development at f94595f on 2026-10-09. Code links point at cab2947; line numbers may have moved since. Finding IDs (F-W1-…) are stable references for this backlog.}