Forced-OCR runs fail: codec-pdf-render not enabled

[martsokha]

Summary

When a workspace sets OcrPolicy::Force (or the engine otherwise needs to rasterize a PDF), detection can fail with CapabilityUnavailable because the engine's codec-pdf-render feature is not enabled. The renderer that turns PDF pages into images for OCR is a separate, opt-in feature that drags in a native rendering dependency, and it is not currently turned on.

Surfaced during the elide-runtime migration review (#232).

How it happens

1. raster_mode_of maps the workspace OcrPolicy:
   • Force → RasterMode::always() — always rasterize pages, ignoring any text layer.
   • Auto → RasterMode::Auto (text layer where present) — unaffected.
   • Never → RasterMode::Never — unaffected.
2. RasterMode::always() requires a page renderer. elide-pipeline's PDF rendering path is gated behind codec-pdf-render (on top of codec-pdf), which pulls a native dep and is off by default.
3. nvisy-server enables all-modalities (tabular/image/audio/document) but not codec-pdf-render.
4. So a Force run on a PDF reaches the decode step and the engine returns ErrorKind::CapabilityUnavailable → surfaced as a 500 (the engine error mapping added in Migrate engine dep to elide-runtime (elide-pipeline) #232 keeps CapabilityUnavailable a server fault, so the failure is at least legible).

This is pre-existing behavior — the old OcrMode::force() had the identical dependency; the migration did not introduce it. It's tracked separately here rather than as a migration rider.

Options (product decision)

• A. Enable codec-pdf-render in nvisy-server's elide-pipeline features. Makes Force work on PDFs, but adds a native rendering dependency to the build (binary size, build time, and the native toolchain requirement in CI/containers).
• B. Reject OcrPolicy::Force (and possibly Never) at validation time when the build can't honor it, so a misconfigured policy fails fast with a clear 400/config error instead of a run-time 500.
• C. Hybrid — enable the renderer in the deployment build, but still validate/guard so a build without it rejects the policy rather than 500ing mid-run.

Recommendation: decide whether forced PDF rasterization is a supported product capability. If yes → A (or C). If it's not a shipped capability → B, so the policy can't be set in a way the deployment can't fulfill.

Acceptance

• A Force-policy detection run on a PDF either succeeds (renderer enabled) or is rejected at policy-set / validation time with a clear client-facing error — never a mid-run 500 CapabilityUnavailable.
• CI/container build implications of any new native dependency are understood and documented.

References

• crates/nvisy-server/src/service/detection/worker.rs — raster_mode_of
• crates/nvisy-server/Cargo.toml — elide-pipeline feature set
• crates/nvisy-server/src/handler/error/engine_error.rs — CapabilityUnavailable → 500 mapping
• Review thread: Migrate engine dep to elide-runtime (elide-pipeline) #232