v2.6.3

PDF Craft v2.6.3

PDF Craft 2.6.3 preserves the original cause of concurrent service failures,
coordinates temporary rate limits across request pools, and replaces automatic
PDF input gating with optional input assertions. It also fixes XML fill text
handling and PDF-to-PCEX directory/chapter consistency during refinement and recovery.
Operation-scoped request headers now propagate across model-service calls.

Operation-scoped request headers

• Model-calling operations accept keyword-only request_headers, including
  synchronous/asynchronous Craft facades and advanced components. Headers reach
  LLM, DeepSeek OCR/OCR2, Unlimited OCR token/submission/polling, and JEV calls,
  including retries and nested translation/fill recovery.
• Each operation snapshots its headers without mutating shared clients or model
  configurations. Concurrent operations remain isolated; nested operations inherit
  headers by default, an explicit mapping replaces them, and {} clears them.
• Headers are not attached to resource downloads or caller-owned image resolvers.
  Authentication, routing and body-framing headers remain client-managed.
• Pass headers to the operation, not the LLM or OCR configuration constructor.
  Applications migrating from experimental instance-level headers support must
  move their mapping to request_headers on each operation.
• See #542 and the
  request-header API.

Concurrent failures

• The first recorded fatal error remains the cause of the operation failing,
  even when sibling cancellation is collected first or cleanup also fails.
• OCR HTTP 402 and HTTP 429 quota failures retain their original HTTP status and
  exception chain. Ordinary user cancellation still propagates as cancellation.
• The same protection applies across OCR, JEV, translation/fill and their
  surrounding pipelines. See #535.

Shared rate-limit recovery

• New optional RateLimitScope() instances coordinate executors using the same
  provider quota. Executors without an explicit scope receive their own scope.
• Temporary limits trigger shared cooldown, one probe request, and gradual,
  spaced recovery. Waiting releases request capacity and supports cancellation.
• Defaults are cooldown_seconds=1.0 and max_wait_seconds=600.0. The latter is
  a separate cumulative waiting budget for each logical request. Exhaustion
  raises RateLimitTimeoutError; existing total request timeouts still apply.
• LLM, JEV and OCR vendor temporary limits no longer consume ordinary retry
  counts, including when those counts are zero. Existing retry parameters remain
  available for non-rate failures and provider-specific recovery.
• Numeric and HTTP-date Retry-After values are supported, along with structured
  LLM rate-limit errors received after a streaming HTTP 200 response starts.
  Payment/quota failures remain fatal, rather than triggering cooldown.
• See #537 and the
  shared rate-limit API.

Optional input checks and migration

• Conversion no longer runs mandatory whole-file PDF preflight. Failures surface
  at the actual operation, retaining supported page-level recovery.
• Applications can explicitly call assert_pdf_readable,
  assert_pdf_renderable, assert_pdf_editable or assert_epub_readable.
  These blocking checks return None or raise the original backend/parser error;
  they do not repair inputs or guarantee a complete conversion.
• Breaking change: PDFPreflightError is removed from pdf_craft and
  pdf_craft.error, together with the automatic gate. Remove its imports and
  catch clauses; optional assertions propagate original backend/parser errors.
• Existing conversion entry points and LLM/OCR configuration parameters remain
  available. See #536 and the
  input-check documentation.

XML fill correctness

• Literal tag-shaped text such as <span> and <xml>, ampersands and XML
  entities now survive friendly XML encoding and decoding. Text and tails are
  decoded once after structural parsing, avoiding double-decoding or turning
  escaped prose into structural elements.
• Fill instructions now permit empty inline formatting slots when a translation
  is shorter than the source's styled spans. They no longer require source-text
  padding that conflicts with the canonical translation. Required tags/IDs and
  strict structural/full-text validation remain enforced.
• Generic XHTML fill no longer receives PCEX-only canonical/formula instructions
  when no canonical validator is configured.
• Fixes #526 and
  #527 in
  #539.

PDF-to-PCEX directory and chapter recovery

• Directory detection preserves actual PDF page numbers for selected or sparse
  page ranges, while using positions within the selected window for heuristics.
  Excluded printed directory pages cannot also become chapter anchors.
• A refined heading containing multiple independent directory anchors now keeps
  each chapter boundary, along with its source fragments, assets and references.
• When refinement invalidates directory/chapter identity, recovery first asks
  the analysis error policy whether to withdraw refinement. Remaining directory
  inconsistencies can be reconciled explicitly without discarding usable body
  text. Page-image recovery also reconciles unavailable anchors while retaining
  surviving chapter IDs.
• Final validation still rejects inconsistent PCEX, with missing/unexpected
  chapter IDs and known source pages included in diagnostics. Actual all-page
  degradation still fails the task.
• See #540. A deterministic
  six-page regression reproduces the failure mechanism described in
  service #229; the exact
  production trigger remains unconfirmed.

PCEX v4 is unchanged.

Full Changelog: v2.6.2...v2.6.3