feat(ops): expose MinerU runtime readiness separately from liveness

[seonghobae]

Summary

Add an unauthenticated GET /ready endpoint that returns 200 only when the MinerU executable required by /parse is discoverable, while preserving GET /health as a process-liveness endpoint.

Buyer-visible gap

The API-only container can currently report a green /health even when MinerU is absent and every real parse request returns 503. Deployment platforms therefore cannot distinguish a live process from a traffic-ready parser instance. This change supplies that missing operational contract.

Changes

• Add a focused runtime-readiness module and router.
• Resolve NEWSDOM_MINERU_BIN on every probe, falling back to mineru on PATH.
• Use executable discovery rather than running an expensive parser subprocess inside a probe.
• Return a sanitized 503 Service Unavailable when MinerU is unavailable.
• Keep /health and /ready unauthenticated even when bearer protection is enabled for /parse.
• Add regression coverage for configured, missing, and default MinerU executable discovery plus HTTP success/failure behavior and security headers.
• Document liveness/readiness separation, Kubernetes probes, Docker Compose behavior, and the release note in CHANGELOG.md.

Verification

• Focused readiness contract: 5 passed.
• New production module and public functions include docstrings.
• Repository quality gate remains responsible for exact-head 100% statement/branch coverage and docstring evidence.
• All hosted security, package, container, and fuzz checks must complete on the final unstacked head before merge.

Standards basis

The contract follows Kubernetes probe semantics: liveness controls restart decisions, while readiness controls whether an instance receives service traffic. The endpoint is intentionally low-cost and returns a minimal response.

Residual risk

This is a shallow readiness check: it proves that an executable can be resolved, not that a particular PDF, model download, GPU backend, or external cache will succeed. Deep parser execution belongs in startup validation, diagnostics, or synthetic monitoring rather than a frequently invoked readiness probe.

Stacked dependency

This draft is intentionally stacked on security PR #467. Until #467 is merged, the comparison against develop also contains its dependency-remediation commits. After #467 lands, the diff contracts to the readiness change alone and this PR must be revalidated on the resulting current head before it is marked ready.

Git Flow target

• feat/* → develop.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fefa3e36-f3d9-49c3-91a4-7e4ef76410be

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Parking this reviewed product slice until security baseline PR #467 is merged. The branch is preserved. Reopen after develop contains #467, rebuild the branch as a clean single-purpose readiness diff, rerun the focused and full exact-head checks, then request independent review and merge through repository policy. Closing now avoids consuming runner and reviewer capacity with a knowingly stacked draft.