Engine · PDF tools

Photo to PDF

Follow an ordered set of page photographs into one PDF, keeping a record of which images were excluded.

Workflow

  1. Choose photographsSupply a captureId and optionally an explicit selection. When selection is present, it wins and retains the user’s order. Empty selections and unknown fixture identities are refused; no fallback silently broadens the request.
  2. Create or reuse scan jobUse JobStore and JobRecovery to claim an attempt. A terminal replay returns the stored result. The current handler runs the scan inside its request while storing durable state; durable does not automatically mean an asynchronous request API.
  3. Order and filter pagesbuild_pageset preserves an explicit order or orders a capture set by its own rules. Record each inclusion or exclusion as a work-unit receipt before moving on. Page-set failure produces a failed job result.
  4. Straighten surviving pagesStraighten each included page photograph. A page that cannot be found is recorded as excluded. OcrPage is used as an assembly record with empty text and skipped OCR; the type name does not mean OCR ran.
  5. PARTIAL · no PDF createdIf no pages survive, the job records partial with no_page_found and the exclusions. The operation returns refused. Do not offer an empty file as a completed PDF.
  6. Assemble page imagesassemble_pdf consumes the surviving JPEG pages, embeds their bytes and creates a PDF artifact. Source hashes and a digest support the receipt. Assembly does not make the photographs searchable.
  7. COMPLETE · record PDF receiptComplete under the current worker lease and return the durable result. Inspect excluded entries even on success: complete can mean a PDF of the pages that survived, not every selected image.
  8. REFUSED / UNAVAILABLEInvalid selection is refused, a missing sandbox root is unavailable, and a page-set exception records failed. Other dependency or assembly exceptions must not be flattened into a successful PDF; the handler does not demonstrate a uniform recovery envelope for every exception.

Failure boundaries

  • Unknown/empty selectionRefused: No broader fallback
  • No sandbox rootUnavailable: No scan starts
  • No page survivesJob partial; operation refused: No PDF offered
  • Some pages excludedPDF can complete: Selected count differs from output
  • Terminal request replayStored result returned: No new successful work implied

engine.pdf.photo-to-pdf