Canonicalize LLM provider endpoints and publish actionable safe failure diagnostics

[xeonvs]

Problem

Provider configuration treated the inference URL as an opaque value, so auxiliary model checks could derive an invalid /models path. A non-zero OCR review also produced only a generic GitLab failure even when the private bounded result contained structured retry facts.

Safe classification limit

Runtime HTTP 404 is endpoint-or-model-not-found. The toolkit cannot safely distinguish endpoint-not-found from model-not-found without trusting provider-controlled response text, so it does not claim that distinction.

Implementation checklist

• Share one provider-neutral URL/protocol/header/request-body owner between ocr-ci configure and ocr-ci preflight.
• Accept API roots and compatible terminal /chat/completions, /responses, and /v1/messages endpoints; reject credentials, fragments, embedded whitespace, and protocol mismatch.
• Preserve an inference query and require explicit OCR_LLM_MODELS_URL when auxiliary derivation is ambiguous.
• Hostile-read non-zero OCR output only through the bounded ocr.llm-retry-report/v1 projection.
• Cover 400, 401, 402, 403, 404, 408, 409, 413, 422, 429, 5xx, 529, timeout, network, invalid response, cancelled, mixed, malformed, oversized, and unknown cases.
• Render only provider-neutral toolkit-authored text; route the legacy billing/quota warning through the same renderer.
• Keep raw provider/model fields, bodies, codes/messages, IDs, paths, warnings, credentials, and classified stderr private; ignore OCR_POST_ERROR_DETAILS=1 for classified failures.
• Preserve the previous successful review, publish no failed-result findings, and keep approval unreachable in advisory and strict modes.
• Add the separate 129.bugfix.md operator/agent-facing changelog fragment and public data-flow documentation.
• Complete focused, full quality/coverage, Gitleaks, manifest/lock, Towncrier, reproducible package, Twine, and Python 3.12–3.14 install gates.

Release lifecycle

• Implemented and pushed at Draft PR Release 0.8.1: completion cap and safe provider failures #131 exact head 53c6374da216bf88aa27ba6dd146b3322d8c8463 (tree 25e4340ce9a076edc28e5412edd11de7ac876d76).
• All hosted checks pass on that exact head.
• Protected feature PR is reviewed and merged.
• TestPyPI development artifact is independently verified.
• Protected 0.8.1 release and external registry/GitHub/provenance reconciliation complete.

Related completion-cap control: #130. Keep this issue open until stable reconciliation.

[github-actions]

Stable v0.8.1 delivery is verified by immutable release asset release-receipt.json in v0.8.1 (SHA-256 453d0522e9b23aa164fe14d68d1d945fade2bc6a40dd0c26aadb76edca775ad2).